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:

1. 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 unique userID of the user.
2. The host maintains heartbeat with the business server.
3. 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 unique roomID of the room.
4. The host calls Express SDK's API createEngineWithAppID to create and initialize a ZegoExpressEngine instance and calls setEventHandler to set an event handler to listen for and handle event callbacks.
5. The host calls Express SDK's API loginRoom to log into the ZEGO room with the userID and roomID obtained in step 1 and step 3 above.
6. 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：

1. 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 unique userID of the user.
2. The listener maintains heartbeat with the business server.
3. The listener sends a get_room_list request to the business server to obtain the chat room list.
4. 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.
5. 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.
6. 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.
7. The listener calls Express SDK's API createEngineWithAppID to create and initialize a ZegoExpressEngine instance and calls Express SDK's API setEventHandler to set an event handler to listen for and handle event callbacks.
8. 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.
9. The listener calls Express SDK's API loginRoom to log into the ZEGO room with the userID obtained in step 1 and the roomID identified in step 4 above.

2.3 A listener requests to join the chat

API call sequence:

The main steps are as follows:

1. The listener sends an operate_raise_hand request to the business server.
2. 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.
3. 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.
4. The host sends a invite_onstage request to the business server to invite the target listener to speak.
5. 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.
6. Upon receiving the onIMRecvCustomCommand event from the Express SDK's callback function, the listener extracts the invitation message from the event data.
7. The listener accepts or rejects the invitation and sends a response_onstage_invite request to the business server accordingly.
8. 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.
9. 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.
10. 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:

1. The host sends an invite_onstage request to the business server to invite the target listener to speak.
2. 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.
3. Upon receiving the onIMRecvCustomCommand event from the Express SDK's callback function, the listener extracts the invitation message from the event data.
4. The listener accepts or rejects the invitation and sends a response_onstage_invite request to the business server accordingly.
5. 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.
6. 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.
7. 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:

1. The host sends a set_user_info request to the business server to change the target guest speaker to listener.
2. The business server updates the target user's role locally upon request.
3. 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.
4. 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.
5. 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:

1. The host sends a set_user_info request to the business server to turn off the target guest speaker's microphone.
2. The business server updates the target guest speaker's microphone status locally upon request.
3. 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.
4. 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.
5. 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

3.2 Zego Express-Audio SDK API