- Documentation
- GoChat
- Client-Side Implementation
Build a Voice Chat App
This guide describes how to implement live voice chat based on ZEGO's GoChat cloud service and Express-Audio SDK.
1 Basic Concepts
1.1 User Roles
In this solution, users in a chat room have the following roles:
- Host
A user who creates a chat room becomes the host of the room. The host of a room manages who can speak in the room.
- Listener
A user who joins an existing room created by someone else becomes a listener in the room. A listener can only listen to the conversation between the host and the guest speakers in the room.
- Guest Speaker
A listener becomes a guest speaker when he/she is invited or admitted by the host to join the conversation in the room. A guest speaker becomes a listener when he/she quits the conversation.
1.2 Features
The voice chat scenarios described in this guide involves the following main features:
- Listeners can be invited or request to join in the chat.
The host of a room can invite any listener in the room to join the conversion, subject to the listener's acceptance. A listener can also request to speak by raising his/her hand, subject to the host's approval.
- Guest speakers can quit or be removed from the chat.
Guest speakers in a room can voluntarily quit the conversation. The host can also remove any guest speaker from the conversation by setting him/her as a listener.
- Guest speakers can be put on mute.
Guest speakers in a room can mute themselves or be muted by the host. A muted guest speaker remains in the conversation.
1.3 System Components
The following system components work together to make a live chat happen.
- Business Server (the chat room backend service)
The business server is a backend service responsible for maintaining the chat room list, room members' roles, the status of users' chat requests, users' microphone status, etc.
To save you development effort and accelerate your time to market, ZEGO can provide you with the source code of this backend service, which you can deploy directly or customize according to your specific needs. For more details, please refer to ZEGO GoChat Cloud Service.
- ZEGO Express-Audio SDK
The ZEGO Express-Audio SDK (referred to as "the Express SDK" hereafter) is used for publishing/playing audio streams. Please refer to SDK Integration for details on how to download and integrate the Express SDK.
- Chat Room Clients - The Host, Listeners, and Guest Speakers
Chat room clients refer to the client apps (in this example, native apps) built with the Express SDK. Chat room clients perform different functions based on their user role in a chat room.
2 Processing Flow
For easy presentation, when we refer to a user role (e.g., host) in the following processing steps, we are referring to the chat room client being used by the user in that role.
2.1 The host starts a chat room
API call sequence:
The main steps are as follows:
- The host sends a
login
request to the business server. The business server records the user information of the host and sends back a response, which includes the uniqueuserID
of the user. - The host maintains
heartbeat
with the business server. - The host sends a
create_room
request to the business server. The business server creates a new room and returns the information of the new room, which includes the uniqueroomID
of the room. - The host calls Express SDK's API
createEngineWithAppID
to create and initialize aZegoExpressEngine
instance and callssetEventHandler
to set an event handler to listen for and handle event callbacks. - The host calls Express SDK's API
loginRoom
to log into the ZEGO room with theuserID
androomID
obtained in step 1 and step 3 above. - The host calls Express SDK's API
startPublishingStream
to start publishing a stream to the target ZEGO room.
2.2 A listener joins the chat room
API call sequence:
The main steps are as follows:
- The listener sends a
login
request to the business server. The business server records the information of the listener and sends back a response, which includes the uniqueuserID
of the user. - The listener maintains
heartbeat
with the business server. - The listener sends a
get_room_list
request to the business server to obtain the chat room list. - The listener selects a chat room to join and sends a
login_room
request to the business server. The business server adds the listener to the room and returns the information of the room. - The business server sends the user update details as a "Room Extra Info" update to ZEGO's backend service, which then synchronizes this update to all Express SDK clients connected to this room.
- Upon receiving the
onRoomExtraInfoUpdate
event from the Express SDK's callback function, room members extract the user list from the event data and refresh the UI accordingly. - The listener calls Express SDK's API
createEngineWithAppID
to create and initialize aZegoExpressEngine
instance and calls Express SDK's APIsetEventHandler
to set an event handler to listen for and handle event callbacks. - The listener sends a
get_attendee_list
to the business server to obtain the user list of the room and displays the user list on the client UI. - The listener calls Express SDK's API
loginRoom
to log into the ZEGO room with theuserID
obtained in step 1 and theroomID
identified in step 4 above.
2.3 A listener requests to join the chat
API call sequence:
The main steps are as follows:
- The listener sends an
operate_raise_hand
request to the business server. - The business server sends the information of the "raise hand" request as a "Room Extra Info" update to ZEGO's backend service, which then synchronizes this update to all Express SDK clients connected to this room.
- Upon receiving the
onRoomExtraInfoUpdate
event from the Express SDK's callback function, room members extract the listener's "raise hand" status change and refresh UI accordingly. - The host sends a
invite_onstage
request to the business server to invite the target listener to speak. - The business server sends the invitation as a custom signaling message to ZEGO's backend service, which then sends this message to the Express SDK client of the target listener.
- Upon receiving the
onIMRecvCustomCommand
event from the Express SDK's callback function, the listener extracts the invitation message from the event data. - The listener accepts or rejects the invitation and sends a
response_onstage_invite
request to the business server accordingly. - If the listener accepts the invitation, the business server sends the user role change as a "Room Extra Info" update to ZEGO's backend service, which then synchronizes this update to all Express SDK clients connected to this room.
- Upon receiving the
onRoomExtraInfoUpdate
event from the Express SDK's callback function, room members extract the user role change from the event data and refresh the UI accordingly. - The listener (who raised hand in step 1) calls Express SDK's API
startPublishingStream
to start publishing a stream to the room if the received event data indicates that his/her role has been changed to guest speaker.
2.4 The host invites a listener to join the chat
API call sequence:
The main steps are as follows:
- The host sends an
invite_onstage
request to the business server to invite the target listener to speak. - The business server sends the invitation as a custom signaling message to ZEGO's backend service, which then sends this message to the Express SDK client of the target listener.
- Upon receiving the
onIMRecvCustomCommand
event from the Express SDK's callback function, the listener extracts the invitation message from the event data. - The listener accepts or rejects the invitation and sends a
response_onstage_invite
request to the business server accordingly. - If the listener accepts the invitation, the business server sends the user role change as a "Room Extra Info" update to ZEGO's backend service, which then synchronizes this update to all Express SDK clients connected to this room.
- Upon receiving the
onRoomExtraInfoUpdate
event from the Express SDK's callback function, room members extract the user role change from the event data and refresh the UI accordingly. - The listener (who raised hand in step 1) calls Express SDK's API
startPublishingStream
to start publishing a stream to the room if the received event data indicates that his/her role has been changed to guest speaker.
2.5 Request a guest speaker to quit the chat
API call sequence:
The main steps are as follows:
- The host sends a
set_user_info
request to the business server to change the target guest speaker to listener. - The business server updates the target user's role locally upon request.
- The business server sends the user role change as a "Room Extra Info" update to ZEGO's backend service, which then synchronizes this update to all Express SDK clients connected to this room.
- Upon receiving the
onRoomExtraInfoUpdate
event from the Express SDK's callback function, room members extract the user role change from the event data and refresh the UI accordingly. - The target guest speaker calls Express SDK's API
stopPublishingStream
to stop the stream publishing to the room if the received event data indicates that his/her role has been changed to listener.
2.6 The host puts a guest speaker on mute
API call sequence:
The main steps are as follows:
- The host sends a
set_user_info
request to the business server to turn off the target guest speaker's microphone. - The business server updates the target guest speaker's microphone status locally upon request.
- The business server sends the microphone status change as a "Room Extra Info" update to ZEGO's backend service, which then synchronizes this update to all Express SDK clients connected to this room.
- Upon receiving the
onRoomExtraInfoUpdate
event from the Express SDK's callback function, room members extract the microphone status change from the event data and refresh the UI accordingly. - The target guest speaker calls Express SDK's API
muteMicrophone
to stop audio capture if the received event data indicates that his/her microphone should be muted.
3 API Reference
3.1 GoChat Cloud Service API
Method | Description |
---|---|
login | Logs in to the business server and obtain user ID. |
logout | Logs out of the business server. |
get_room_list | Gets chat room list from the business server. |
create_room | Creates a chat room. |
login_room | Joins a chat room. |
get_attendee_list | Lists all users in a chat room. |
operate_raise_hand | Raises hand or lowers hand. |
set_user_info | Changes user's role or microphone status. |
invite_onstage | Invites a user to the stage (to join the chat). |
response_onstage_invite | Responds to an on-stage invitation. |
For the complete list of APIs, please refer to GoChat Cloud Service .
3.2 Zego Express-Audio SDK API
Method | Description |
---|---|
createEngineWithAppID | Creates a singleton instance of ZegoExpressEngine. |
setEventHandler | Sets an event handler to listen for and handle event callbacks. |
loginRoom | Logs in to a room. |
startPublishingStream | Starts publishing a stream. |
stopPublishingStream | Stops publishing a stream. |
startPlayingStream | Starts playing a remote stream. |
stopPlayingStream | Stops playing a remote stream. |
muteMicrophone | Mutes or unmutes the microphone. |
onRoomExtraInfoUpdate | The callback triggered when there is an update on the room's extra information. |
onIMRecvCustomCommand | The callback triggered when a Custom Command is received. |
For the complete list of APIs, please refer to Express Audio SDK APIs.