Channel Management

getUserInfoByUid

Gets user information by passing in a user ID.

virtual int getUserInfoByUid(uid_t uid, rtc::UserInfo* userInfo) = 0;

After a remote user joins the channel, the SDK obtains the user ID and user account, caches them in a mapping table, and triggers the onUserInfoUpdated callback on the local client. After receiving the callback, you can call getUserInfoByUid and pass in the user ID to get the corresponding user account from the UserInfo object.

Timing

Call this method after receiving the onUserInfoUpdated callback.

Parameters

uid
uid, representing the user ID.
userInfo
Input and output parameter representing user information. The input is a UserInfo object, and the output is a UserInfo object containing the user account and user ID. See UserInfo.

Return Values

  • 0: Success.
  • < 0: Failure.

getUserInfoByUidEx

Retrieves user information by user ID.

virtual int getUserInfoByUidEx(uid_t uid, rtc::UserInfo* userInfo, const RtcConnection& connection) = 0;

This method retrieves user information by passing in the user ID. It functions the same as getUserInfoByUid.

Scenario

Applicable in multi-channel scenarios.

Parameters

uid
User ID of the remote user.
userInfo
Input and output parameter representing the UserInfo object for identifying the user. The UserInfo object passed in when calling this method will return a UserInfo object containing the User Account and user ID upon success. See UserInfo.
connection
RtcConnection object. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

getUserInfoByUserAccount

Gets remote user information by passing in a user account.

virtual int getUserInfoByUserAccount(const char* userAccount, rtc::UserInfo* userInfo) = 0;

After a remote user joins the channel, the SDK obtains the user ID and user account and caches them in a mapping table, while triggering the onUserInfoUpdated callback on the local client. After receiving the callback, you can call this method and pass in the user account to get the user ID from the UserInfo object.

Timing

Call this method after receiving the onUserInfoUpdated callback.

Parameters

userAccount
The user account.
userInfo
Output parameter that represents user information. See UserInfo.

Return Values

  • 0: Success.
  • < 0: Failure.

getUserInfoByUserAccountEx

Retrieves user information by User Account.

virtual int getUserInfoByUserAccountEx(const char* userAccount, rtc::UserInfo* userInfo, const RtcConnection& connection) = 0;

This method retrieves user information by passing in the User Account. It functions the same as getUserInfoByUserAccount.

Scenario

This method is applicable in multi-channel scenarios.

Parameters

userAccount
User Account. Make sure to set this parameter.
userInfo
Input and output parameter representing the UserInfo object for identifying the user. After calling this method, the object contains the User Account and user ID. See UserInfo.
connection
RtcConnection object. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

joinChannel [1/2]

Joins a channel.

virtual int joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) = 0;

By default, a user subscribes to the audio and video streams of all other users in the channel, which incurs usage and billing. To stop subscribing to specific or all remote streams, call muteRemoteAudio/VideoStream or muteAllRemoteAudio/VideoStreams.

Note:
  • This method only supports joining one channel at a time.
  • Users with different App IDs cannot communicate with each other.
  • Before joining a channel, ensure that the App ID used to generate the token is the same as the one passed in initialize, otherwise joining the channel may fail.

Timing

You must call this method after calling initialize.

Related Callbacks

After successfully calling this method, the SDK triggers the following callbacks: If the local client disconnects from the Agora server due to poor network conditions, the SDK attempts to reconnect. When the local client successfully rejoins the channel, the SDK triggers the onRejoinChannelSuccess callback locally.

Parameters

token
The token used for authentication, generated by your server.
Note:
  • (Recommended) If your project enables the security mode (authentication using App ID and token), this parameter is required.
  • If you only enable test mode (authentication using App ID), this parameter is optional. After successfully joining the channel, you will automatically leave the channel after 24 hours.
  • If you need to join multiple channels or switch between channels, Agora recommends using a wildcard token so you don’t need to request a new token each time you join a channel.
channelId
Channel name. Under the same App ID, users who enter the same channel name will join the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters (89 total):
  • All lowercase letters: a to z.
  • All uppercase letters: A to Z.
  • All numeric digits: 0 to 9.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
info
(Optional) Reserved parameter.
uid
User ID. Used to identify users in the channel for real-time audio and video interaction. You must set and manage the user ID yourself and ensure it is unique within the same channel. This parameter is a 32-bit unsigned integer ranging from 1 to 2^32 - 1. If no user ID is specified (or set to 0), the SDK automatically assigns a random user ID and returns it in the onJoinChannelSuccess callback. Your application must record and maintain the returned user ID; the SDK does not store it.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameters. For example, the token is invalid, the uid parameter is not set to an integer, or a member value in ChannelMediaOptions is invalid. You need to pass in valid parameters and rejoin the channel.
    • -3: IRtcEngine initialization failed. You need to reinitialize the IRtcEngine object.
    • -7: The IRtcEngine object is not initialized. You must initialize the IRtcEngine object before calling this method.
    • -8: Internal state error of the IRtcEngine object. A typical reason is calling this method to join a channel after startEchoTest without stopping the test using stopEchoTest. You need to call stopEchoTest before calling this method.
    • -17: Join channel request was rejected. A typical reason is that the user is already in the channel. Agora recommends using the onConnectionStateChanged callback to determine whether the user is in the channel. Only call this method when you receive the CONNECTION_STATE_DISCONNECTED (1) state.
    • -102: Invalid channel name. You need to pass a valid channel name in channelId and rejoin the channel.
    • -121: Invalid user ID. You need to pass a valid user ID in uid and rejoin the channel.

joinChannel [2/2]

Joins a channel and sets media options.

virtual int joinChannel(const char* token, const char* channelId, uid_t uid, const ChannelMediaOptions& options) = 0;

Compared with joinChannel [1/2], this method adds the options parameter to set media options, such as whether to publish audio and video streams in the channel or whether to automatically subscribe to all remote users' audio and video streams when joining the channel. By default, the user subscribes to all other users' audio and video streams in the channel, which incurs usage and billing. To stop subscribing to other streams, set the options parameter or call muteRemoteAudio/VideoStream or muteAllRemoteAudio/VideoStreams.

Note:
  • This method only supports joining one channel at a time.
  • Users with different App IDs cannot communicate with each other.
  • Before joining a channel, ensure that the App ID used to generate the token matches the App ID passed in the initialize method; otherwise, joining the channel may fail.

Timing

Call this method after calling the initialize method.

Related Callbacks

After this method is successfully called, the SDK triggers the following callbacks: If the local client gets disconnected from the Agora server due to poor network conditions, the SDK attempts to reconnect. Once reconnected, the onRejoinChannelSuccess callback is triggered on the local client.

Parameters

token
The token generated on your server for authentication.
Note:
  • (Recommended) If your project has enabled secure mode (authentication using App ID and token), this parameter is required.
  • If you have only enabled test mode (authentication using App ID), this parameter is optional. After successfully joining the channel, the client will automatically leave the channel after 24 hours.
  • If you need to join multiple channels simultaneously or switch between channels, Agora recommends using a wildcard token so that you do not need to request a new token each time you join a channel.
channelId
The channel name. Users with the same App ID who enter the same channel name join the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters (total 89):
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
uid
The user ID, used to identify the user in the channel for real-time audio and video interaction. You must set and manage the user ID yourself and ensure that each user ID is unique within the same channel. This parameter is a 32-bit unsigned integer, with a value range of 1 to 2^32-1. If the user ID is not specified (or set to 0), the SDK automatically assigns a random user ID and returns it in the onJoinChannelSuccess callback. Your application must record and maintain the returned user ID.
options
Channel media options. See ChannelMediaOptions.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter. For example, the token is invalid, the uid parameter is not set to an integer, or the values of members in ChannelMediaOptions are invalid. You must pass valid parameters and rejoin the channel.
    • -3: Failed to initialize the IRtcEngine object. You need to reinitialize the IRtcEngine object.
    • -7: The IRtcEngine object has not been initialized. You must initialize the IRtcEngine object before calling this method.
    • -8: Internal state error of the IRtcEngine object. A typical cause is calling this method to join a channel without calling stopEchoTest after starting a call loop test with startEchoTest. You must call stopEchoTest before calling this method.
    • -17: The request to join the channel was rejected. A typical cause is that the user is already in the channel. Agora recommends determining whether the user is in a channel by listening for the onConnectionStateChanged callback. Only call this method when receiving the CONNECTION_STATE_DISCONNECTED (1) state.
    • -102: Invalid channel name. You need to pass a valid channel name in channelId to rejoin the channel.
    • -121: Invalid user ID. You need to pass a valid user ID in uid to rejoin the channel.

joinChannelEx

Joins a channel.

virtual int joinChannelEx(const char* token, const RtcConnection& connection, const ChannelMediaOptions& options, IRtcEngineEventHandler* eventHandler) = 0;

You can call this method multiple times to join multiple channels. In multi-camera capture scenarios, after calling this method, you need to call the startPreview method and set sourceType to VIDEO_SOURCE_CAMERA_SECONDARY to ensure the secondary camera captures properly.

Note: If you are already in a channel, you cannot rejoin the same channel using the same user ID. Before joining a channel, make sure the App ID used to generate the token is the same as the App ID passed in the initialize method, otherwise joining the channel with the token may fail.

Scenario

This method applies to multi-channel scenarios.

Timing

Call this method after calling the initialize method.

Related Callbacks

After successfully calling this method, the SDK triggers the following callbacks: If the connection between the local client and the Agora server is interrupted due to poor network conditions, the SDK attempts to reconnect. When the local client successfully rejoins the channel, the SDK triggers the onRejoinChannelSuccess callback on the local client.

Parameters

token
The token used for authentication, generated by your server.
Note:
  • (Recommended) If your project has enabled secure mode (authentication using App ID and token), this parameter is required.
  • If you only enabled test mode (authentication using App ID), this parameter is optional. After successfully joining the channel, you will automatically leave the channel after 24 hours.
  • If you need to join different channels simultaneously or switch between channels, Agora recommends using a wildcard token so you don't have to request a new token each time. See Secure authentication with tokens.
connection
Connection information. See RtcConnection.
options
Channel media options. See ChannelMediaOptions.
eventHandler
Callback class. See IRtcEngineEventHandler. You can use the eventHandler object passed through this parameter to get callback events for multiple channels.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter. For example, the token is invalid, the uid parameter is not set to an integer, or a member value in ChannelMediaOptions is invalid. You need to pass in valid parameters and rejoin the channel.
    • -3: IRtcEngine object initialization failed. You need to reinitialize the IRtcEngine object.
    • -7: IRtcEngine object is not initialized. You need to initialize the IRtcEngine object before calling this method.
    • -8: Internal state error of the IRtcEngine object. A typical cause is calling this method to join a channel after calling startEchoTest without calling stopEchoTest to stop the test. You need to call stopEchoTest before calling this method.
    • -17: Join channel request is rejected. A typical reason is that the user is already in the channel. Agora recommends checking the user's channel status via the onConnectionStateChanged callback. Only call this method to join the channel when receiving the CONNECTION_STATE_DISCONNECTED (1) state.
    • -102: Invalid channel name. You need to pass a valid channel name in channelId to rejoin the channel.
    • -121: Invalid user ID. You need to pass a valid user ID in uid to rejoin the channel.

joinChannelWithUserAccount [1/2]

Joins a channel using a user account and token.

virtual int joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) = 0;

Before calling this method, if you have not yet called registerLocalUserAccount to register a user account, the SDK automatically creates one for you when you call this method to join a channel. It is recommended to call registerLocalUserAccount first and then use this method to join a channel to reduce the time required to join. After a user joins a channel, they subscribe to all other users' audio and video streams by default, which generates usage and billing. To stop subscribing to specific or all remote streams, call setRemoteAudio/VideoStream or setAllRemoteAudio/VideoStreams.

Note:
  • This method only supports joining one channel at a time.
  • Users with different App IDs cannot communicate with each other.
  • Before joining a channel, ensure that the App ID used to generate the token matches the App ID passed in the initialize method, otherwise joining the channel may fail.
  • To ensure smooth communication, use the same parameter type to identify users. For example, if one user joins with a user ID, others should also use user IDs; if joining with a user account, others should also use user accounts. If users join the channel using the Agora Web SDK, ensure that the user ID type is consistent.

Timing

Call this method after calling initialize.

Related Callbacks

After successfully calling this method, the SDK triggers the following callbacks:

Parameters

token
The token generated on your server for authentication.
Note:
  • (Recommended) If your project enables security mode (authentication using App ID and token), this parameter is required.
  • If you enable only testing mode (authentication using App ID), this parameter is optional. After successfully joining the channel, you will be automatically disconnected after 24 hours.
  • If you need to join multiple channels simultaneously or switch between channels, Agora recommends using a wildcard token so you do not need to request a new token each time you join a channel.
channelId
The channel name. Users with the same App ID and channel name join the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters (89 total):
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric digits: 0 to 9.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
userAccount
The user account. You need to set and manage the user account yourself and ensure that each user account is unique within the same channel. The maximum length of this parameter is 255 bytes and it cannot be empty. Supported characters (89 total):
  • 26 lowercase English letters: a to z.
  • 26 uppercase English letters: A to Z.
  • All numeric digits: 0 to 9.
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter. For example, the token is invalid, the uid parameter is not set to an integer, or a member of ChannelMediaOptions has an invalid value. Pass in valid parameters and rejoin the channel.
    • -3: IRtcEngine object initialization failed. Reinitialize the IRtcEngine object.
    • -7: IRtcEngine object not initialized. Initialize the IRtcEngine object before calling this method.
    • -8: Internal state error of the IRtcEngine object. A common cause is calling this method to join a channel after calling startEchoTest to start an echo test without calling stopEchoTest to stop it. Call stopEchoTest before calling this method.
    • -17: Join channel request rejected. A common cause is the user is already in the channel. Agora recommends checking the user's connection status using the onConnectionStateChanged callback and only calling this method when receiving the CONNECTION_STATE_DISCONNECTED (1) state.
    • -102: Invalid channel name. Pass a valid channel name in channelId and rejoin the channel.
    • -121: Invalid user ID. Pass a valid user ID in uid and rejoin the channel.

joinChannelWithUserAccount [2/2]

Joins a channel using a user account and token, and sets media options.

virtual int joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount, const ChannelMediaOptions& options) = 0;

Before calling this method, if you have not called registerLocalUserAccount to register a user account, the SDK automatically creates a user account when you call this method to join a channel. Calling registerLocalUserAccount in advance can reduce the time needed to join the channel. Compared with the joinChannelWithUserAccount method, this method adds the options parameter, which allows you to set media options in the channel, such as whether to publish audio and video streams. By default, a user subscribes to all audio and video streams from other users in the channel, which results in usage and billing. To stop subscribing to other streams, set the options parameter or call muteRemoteAudio/VideoStream or muteAllRemoteAudio/VideoStreams.

Note: This method only supports joining one channel at a time. Users with different App IDs cannot communicate with each other. Before joining a channel, ensure that the App ID used to generate the token is the same as the App ID passed to the initialize method; otherwise, the channel join may fail. To ensure smooth communication, use the same type of user identifier. For example, if one user joins the channel with a user ID, other users should also use a user ID; the same applies to using a user account. If a user joins the channel using the Agora Web SDK, make sure the parameter type of the user ID is consistent.

Timing

Call this method after calling the initialize method.

Related Callbacks

After this method is successfully called, the SDK triggers the following callbacks:

Parameters

token
The token generated on your server for authentication.
Note:
  • (Recommended) If your project has enabled the security mode (authentication using App ID and token), this parameter is required.
  • If you have only enabled the testing mode (authentication using App ID), this parameter is optional. After successfully joining the channel, you will automatically leave the channel after 24 hours.
  • If you need to join multiple channels or switch between channels, Agora recommends using a wildcard token so that you do not need to request a new token each time you join a channel.
channelId
The channel name. This parameter specifies the channel for real-time audio and video interaction. Users with the same App ID and channel name join the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters (89 total):
  • All lowercase letters: a to z.
  • All uppercase letters: A to Z.
  • All numeric characters: 0 to 9.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ",".
userAccount
The user account. Used to identify the user in the channel for real-time audio and video interaction. You need to set and manage the user account yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes and it cannot be empty. Supported characters (89 total):
  • 26 lowercase letters: a to z.
  • 26 uppercase letters: A to Z.
  • All numeric characters: 0 to 9.
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ",".
options
Channel media options. See ChannelMediaOptions.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter. For example, the token is invalid, the uid parameter is not set to an integer, or a value in ChannelMediaOptions is invalid. You need to pass in valid parameters and rejoin the channel.
    • -3: IRtcEngine object failed to initialize. You need to reinitialize the IRtcEngine object.
    • -7: IRtcEngine object is not initialized. You need to initialize the IRtcEngine object before calling this method.
    • -8: Internal state error of the IRtcEngine object. A typical cause is calling this method to join a channel after starting an echo test with startEchoTest but not stopping it with stopEchoTest. You need to call stopEchoTest before calling this method.
    • -17: The request to join the channel is rejected. A typical cause is that the user is already in the channel. Agora recommends using the onConnectionStateChanged callback to check if the user is in the channel. Only call this method when the state is CONNECTION_STATE_DISCONNECTED (1).
    • -102: Invalid channel name. You need to pass a valid channel name in channelId to rejoin the channel.
    • -121: Invalid user ID. You need to pass a valid user ID in uid to rejoin the channel.

joinChannelWithUserAccountEx

Joins a channel using a user account and token, and sets media options.

virtual int joinChannelWithUserAccountEx(const char* token, const char* channelId, const char* userAccount, const ChannelMediaOptions& options, IRtcEngineEventHandler* eventHandler) = 0;

If you have not called registerLocalUserAccount to register a user account before calling this method, the SDK automatically creates one when you join the channel. Calling registerLocalUserAccount in advance can reduce the time required to join the channel. After a user joins a channel, they subscribe to all other users' audio and video streams by default, which incurs usage and billing. To stop subscribing to other users’ media streams, set the options parameter or call muteRemoteAudio/VideoStream or muteAllRemoteAudio/VideoStreams.

Note:
  • This method only supports joining one channel at a time.
  • Users with different App IDs cannot communicate with each other.
  • Before joining a channel, ensure that the App ID used to generate the token matches the one passed to initialize, or the token may fail.
  • To ensure smooth communication, use the same parameter type to identify users. For example, if one user joins with a UID, others should also use a UID; if using a user account, others should also use a user account. If using the Agora Web SDK, ensure the user ID parameter types are consistent.

Scenario

This method applies to multi-channel scenarios.

Timing

Call this method after calling initialize.

Related Callbacks

After successfully calling this method, the SDK triggers the following callbacks:

Parameters

token
The token for authentication, generated on your server.
Note:
  • (Recommended) If your project has enabled secure mode (authentication with App ID and token), this parameter is required.
  • If you only enabled test mode (authentication with App ID), this parameter is optional. You will automatically leave the channel after 24 hours.
  • If you need to join multiple channels or switch between them, Agora recommends using a wildcard token so you don’t need to request a new token every time.
channelId
Channel name. Users with the same App ID and channel name join the same channel. The string length must be less than 64 bytes. Supported characters (89 total):
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
userAccount
The user account used to identify the user in the channel. You must manage user accounts yourself and ensure uniqueness within a channel. Maximum length is 255 bytes and cannot be empty. Supported characters (89 total):
  • 26 lowercase English letters: a to z.
  • 26 uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
options
Channel media options. See ChannelMediaOptions.
eventHandler
Callback class. See IRtcEngineEventHandler. Use the eventHandler object passed in this parameter to get callback events for multiple channels.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter. For example, the token is invalid, the uid parameter is not set as an integer, or a member value in ChannelMediaOptions is invalid. You need to pass in valid parameters and rejoin the channel.
    • -3: IRtcEngine initialization failed. You need to reinitialize the IRtcEngine object.
    • -7: IRtcEngine is not initialized. Initialize IRtcEngine before calling this method.
    • -8: Internal state error. A typical reason is calling this method to join a channel after starting the echo test with startEchoTest without stopping it with stopEchoTest. Call stopEchoTest before calling this method.
    • -17: Join channel request is rejected. A typical reason is that the user is already in a channel. Agora recommends using the onConnectionStateChanged callback to determine whether the user is in a channel. Only call this method when receiving the CONNECTION_STATE_DISCONNECTED (1) state.
    • -102: Invalid channel name. Pass in a valid channel name in channelId and rejoin the channel.
    • -121: Invalid user ID. Pass in a valid user ID in uid and rejoin the channel.

leaveChannel [1/2]

Leaves the channel.

virtual int leaveChannel() = 0;

After calling this method, the SDK stops audio and video interaction, leaves the current channel, and releases all resources related to the session. After joining a channel, you must call this method to end the call, otherwise you cannot start the next call.

Note:
  • If you call release immediately after this method, the SDK does not trigger the onLeaveChannel callback.
  • This is an asynchronous method. When the method returns, it does not mean the user has completely left the channel.
  • If you joined multiple channels using joinChannelEx, calling this method leaves all the channels you joined.

Timing

Call this method after joining the channel.

Related Callbacks

After this method is successfully called, the SDK triggers the following callbacks:
  • Local client: Triggers the onLeaveChannel callback.
  • Remote client: Triggers the onUserOffline callback when the remote host leaves the channel.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -1: A general error occurred (no specific reason).
    • -2: Invalid parameter.
    • -7: SDK not initialized.

leaveChannel [2/2]

Sets channel options and leaves the channel.

virtual int leaveChannel(const LeaveChannelOptions& options) = 0;

After calling this method, the SDK stops audio and video interaction, leaves the current channel, and releases all resources related to the session. If you joined multiple channels using joinChannelEx, calling this method leaves all the channels you joined.

Note: If you call release immediately after this method, the SDK does not trigger the onLeaveChannel callback. This is an asynchronous method. When the method returns, it does not mean the user has left the channel.

Timing

Call this method after joining the channel.

Related Callbacks

After this method is successfully called, the SDK triggers the following callbacks:
  • Local client: Triggers the onLeaveChannel callback.
  • Remote client: Triggers the onUserOffline callback when the remote host leaves the channel.

Parameters

options
Options for leaving the channel. See LeaveChannelOptions.

Return Values

  • 0: Success.
  • < 0: Failure.

leaveChannelEx [1/2]

Leaves a channel.

virtual int leaveChannelEx(const RtcConnection& connection) = 0;
After calling this method, the SDK stops audio and video interaction, leaves the current channel, and releases all resources related to the session. After joining a channel using joinChannelEx, you must call this method or leaveChannelEx to end the call, otherwise you cannot start the next call.
  • If you call release immediately after this method, the SDK does not trigger the onLeaveChannel callback.
  • This method is asynchronous. The return of the method does not indicate that the user has completely left the channel.
  • If you call leaveChannel, you will leave all channels joined using joinChannel or joinChannelEx.

Scenario

This method applies to multi-channel scenarios.

Timing

Call this method after calling joinChannelEx.

Related Callbacks

After successfully calling this method, the SDK triggers the following callbacks:
  • Local client: Triggers the onLeaveChannel callback.
  • Remote client: Triggers the onUserOffline callback when the remote user leaves the channel.

Parameters

connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

leaveChannelEx [2/2]

Sets channel options and leaves the channel.

virtual int leaveChannelEx(const RtcConnection& connection, const LeaveChannelOptions& options) = 0;
Since
Added since v4.1.0.

After calling this method, the SDK stops audio and video interaction, leaves the current channel, and releases all resources related to the session. After joining a channel using joinChannelEx, you must call this method or leaveChannelEx to end the call, otherwise you cannot start the next call.

Note:

Scenario

This method applies to multi-channel scenarios.

Timing

Call this method after calling joinChannelEx.

Related Callbacks

After successfully calling this method, the SDK triggers the following callbacks:
  • Local client: Triggers the onLeaveChannel callback.
  • Remote client: Triggers the onUserOffline callback when the remote host leaves the channel.

Parameters

connection
Connection information. See RtcConnection.
options
Options for leaving the channel. See LeaveChannelOptions.
Note: This parameter only supports setting the stopMicrophoneRecording member in LeaveChannelOptions. Setting other members is invalid.

Return Values

  • 0: Success.
  • < 0: Failure.

preloadChannel

Preloads the specified channel to reduce the time it takes for an audience member to join.

virtual int preloadChannel(const char* token, const char* channelId, uid_t uid) = 0;

When audience members frequently switch between different channels, calling this method can reduce the time it takes to join a channel, thereby reducing the delay in hearing or seeing the host. If you join a preloaded channel, leave it, and want to rejoin it, you do not need to call this method again unless the Token used for preloading has expired.

Note:
  • When calling this method, ensure the user role is set to audience and the audio scenario is not set to AUDIO_SCENARIO_CHORUS, otherwise this method will not take effect.
  • Ensure that the channel name, user ID, and Token used for preloading are the same as those used when joining the channel, otherwise this method will not take effect.
  • One IRtcEngine instance supports up to 20 preloaded channels. If this limit is exceeded, only the latest 20 preloaded channels take effect.
  • Failing to preload a channel does not affect the ability to join the channel or increase the time needed to join.

Timing

To improve the user experience of channel preloading, Agora recommends calling this method as early as possible after confirming the channel name and user information.

Parameters

token
The Token used for authentication, generated by your server. When the Token expires, you can update it based on the number of preloaded channels:
  • To preload one channel, call this method with the new Token.
  • To preload multiple channels:
    • If you use a wildcard Token for all channels, call updatePreloadChannelToken to update the Token. Ensure the user ID is not 0 when generating the wildcard Token.
    • If you use different Tokens for different channels, call this method with your user ID, channel name, and new Token.
channelId
The name of the channel you want to preload. This parameter represents the channel where users interact via real-time audio and video. Users with the same channel name under the same App ID will join the same channel. The channel name must be less than 64 bytes. Supported characters (89 total):
  • All lowercase letters: a to z.
  • All uppercase letters: A to Z.
  • All numeric characters: 0 to 9.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ",".
uid
The user ID used to identify a user in the channel for real-time audio and video interaction. You must set and manage the user ID yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer ranging from 1 to 2^32 - 1. If the user ID is not specified (or set to 0), the SDK assigns a random user ID and returns it in the onJoinChannelSuccess callback. Your app must record and maintain the returned user ID; the SDK does not save it.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -7: The IRtcEngine object is not initialized. Please initialize IRtcEngine before calling this method.
    • -102: The channel name is invalid. Please provide a valid channel name and rejoin the channel.

preloadChannelWithUserAccount

Preloads the specified channel.

virtual int preloadChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) = 0;

When audience users frequently switch between different channels, calling this method can reduce the time it takes to join a channel, thereby reducing the delay in hearing or seeing the host. If you join a preloaded channel, leave it, and want to rejoin it, you do not need to call this method again unless the Token used for preloading has expired.

Note:
  • When calling this method, ensure the user role is set to audience and the audio scenario is not set to AUDIO_SCENARIO_CHORUS, otherwise this method will not take effect.
  • Also ensure that the user account, channel name, and Token used for preloading are the same as those used when joining the channel, otherwise this method will not take effect.
  • One IRtcEngine instance supports up to 20 preloaded channels. If this limit is exceeded, only the latest 20 preloaded channels take effect.
  • Failing to preload a channel does not affect the ability to join the channel or increase the time needed to join.

Timing

To improve the user experience of channel preloading, Agora recommends calling this method as early as possible after confirming the channel name and user information.

Parameters

token
The Token used for authentication, generated by your server. When the Token expires, you can update it based on the number of preloaded channels:
  • To preload one channel, call this method with the new Token.
  • To preload multiple channels:
    • If you use a wildcard Token for all preloaded channels, call updatePreloadChannelToken to update the Token. Note: Ensure the user ID is not 0 when generating the wildcard Token.
    • If you use different Tokens for different channels, call this method with the user ID, channel name, and new Token.
channelId
The name of the channel you want to preload. Users with the same channel name under the same App ID will join the same channel. The channel name must be less than 64 bytes. Supported characters (89 total):
  • All lowercase letters: a to z.
  • All uppercase letters: A to Z.
  • All numeric characters: 0 to 9.
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ",".
userAccount
The user account. You must set and manage the user account yourself, and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes and it cannot be empty. Supported characters (89 total):
  • 26 lowercase letters: a to z.
  • 26 uppercase letters: A to Z.
  • All numeric characters: 0 to 9.
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ",".

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter, e.g., empty user account. Please pass in valid parameters and rejoin the channel.
    • -7: The IRtcEngine object is not initialized. Please initialize IRtcEngine before calling this method.
    • -102: The channel name is invalid. Please provide a valid channel name and rejoin the channel.

registerLocalUserAccount

Registers a user account.

virtual int registerLocalUserAccount(const char* appId, const char* userAccount) = 0;
This method registers a user account. After successful registration, the user account can be used to identify the local user when joining a channel. You can choose one of the following methods to join a channel using a user account:
  • First call registerLocalUserAccount to register the user account, then call joinChannelWithUserAccount to join the channel. This can reduce the time needed to join the channel.
  • Directly call joinChannelWithUserAccount to join the channel.
Starting from v4.6.0, the SDK no longer automatically maps an int type user ID to the string type userAccount used during registration. If you want to join a channel with the original string type userAccount you registered, use joinChannelWithUserAccount instead of calling joinChannel with the int type user ID obtained from this method.Ensure that userAccount is unique within the channel.To ensure smooth communication, it is recommended to identify users using the same parameter type. For example, if one user joins the channel with a user ID, other users should also use user IDs; similarly, if one uses a user account, others should also use user accounts. If users join the channel using the Agora Web SDK, ensure that the user ID uses the same parameter type.

Related Callbacks

After successfully calling this method, the SDK triggers the onLocalUserRegistered callback to report the local user's user ID and user account.

Parameters

appId
The App ID of your project in the Agora Console.
userAccount
The user account used to identify the user in a channel for real-time audio and video interaction. You need to set and manage the user account yourself and ensure that each user account is unique within the same channel. The maximum length of this parameter is 255 bytes and it cannot be empty. Supported characters (89 total) include:
  • 26 lowercase English letters: a to z.
  • 26 uppercase English letters: A to Z.
  • All numeric digits: 0 to 9.
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

Return Values

  • 0: Success.
  • < 0: Failure.

renewToken

Updates the Token.

virtual int renewToken(const char* token) = 0;
After this method is successfully called, the SDK triggers the onRenewTokenResult callback. The Token expires after a period of time, at which point the SDK cannot connect to the server. Agora recommends that you generate a new Token on your server and call this method to update it in any of the following situations:

Parameters

token
The new Token.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter, such as an empty Token.
    • -7: The IRtcEngine object is not initialized. Please initialize the IRtcEngine object before calling this method.
    • 110: The Token is invalid. Please ensure the following:
      • The user ID specified when generating the Token is the same as the one used to join the channel.
      • The generated Token is the same as the one passed in when joining the channel.

setChannelProfile

Sets the channel profile.

virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0;

The SDK adopts different optimization strategies based on the channel profile. For example, in the live broadcasting profile, the SDK prioritizes video quality. After initializing the SDK, the default channel profile is live broadcasting.

Note: To ensure communication quality, Agora recommends that all users in the channel use the same channel profile. The SDK also uses different default audio routes in different channel profiles. See setDefaultAudioRouteToSpeakerphone.

Timing

Call this method before joining a channel.

Parameters

profile
Channel profile. See CHANNEL_PROFILE_TYPE.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter.
    • -7: SDK not initialized.

setClientRole [1/2]

Sets the user role.

virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0;
  • By default, the SDK sets the user role to audience. You can call this method to set the user role to broadcaster. The user role (role) determines the user's permission at the SDK level, including whether they can publish audio and video streams in the channel.
  • If you call this method before joining a channel to set the user role to broadcaster and set local video properties via setupLocalVideo, the local video preview is automatically enabled when the user joins the channel.
  • If you call this method after joining a channel to set the user role, the SDK automatically calls muteLocalAudioStream and muteLocalVideoStream to update the publishing status of audio and video streams.
Note: When calling this method before joining a channel and setting the user role to BROADCASTER, the local client does not trigger the onClientRoleChanged callback; but if role is set to AUDIENCE, the callback is triggered.

Timing

You can call this method before or after joining a channel.

Related Callbacks

If you call this method to switch the user role after joining a channel, the SDK triggers the following callbacks:
  • Local client: Triggers the onClientRoleChanged callback. Note: Calling this method before joining a channel and setting role to AUDIENCE also triggers this callback.
  • Remote client: Triggers the onUserJoined or onUserOffline callback.
If you call this method after joining a channel and fail to set the user role, the SDK triggers the onClientRoleChangeFailed callback to report the failure reason and current user role.

Parameters

role
User role. See CLIENT_ROLE_TYPE.
Note: If you set the user role to audience, you cannot publish audio and video streams in the channel. To publish media streams during a live broadcast, make sure to set the user role to broadcaster.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -1: A general error occurred (no specific reason).
    • -2: Invalid parameter.
    • -7: SDK not initialized.

setClientRole [2/2]

Sets the user role and audience latency level.

virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0;
This method sets the user role and audience latency level. You can call this method to set the user role to broadcaster. The role parameter determines the user's privileges at the SDK level, such as whether the user can publish audio and video streams in the channel. Compared to setClientRole, this method supports setting audienceLatencyLevel. You must use audienceLatencyLevel together with role to determine the service level the user can access within their privileges. For example, audience users can choose to receive low-latency or ultra-low-latency remote streams.
  • If you call this method before joining a channel and set the user role to broadcaster, and configure local video properties using setupLocalVideo, the local video preview automatically starts when the user joins the channel.
  • If you call this method to change the user role after joining a channel, the SDK automatically calls muteLocalAudioStream and muteLocalVideoStream to change the publishing state of the audio and video streams.
Note: When the user role is set to broadcaster, the audience latency level can only be set to AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY. If you call this method before joining a channel and set role to BROADCASTER, the local client does not trigger the onClientRoleChanged callback. If you call this method before joining a channel and set role to AUDIENCE, the callback is triggered.

Timing

You can call this method before or after joining a channel.

Related Callbacks

If you call this method to switch the user role after joining a channel, the SDK triggers the following callbacks:
  • The local client receives the onClientRoleChanged callback. Note: Calling this method before joining a channel and setting role to AUDIENCE also triggers this callback.
  • The remote client receives the onUserJoined or onUserOffline callback.
If the method call to set the user role fails after joining a channel, the SDK triggers the onClientRoleChangeFailed callback to report the failure reason and the current user role.

Parameters

role
The user role. See CLIENT_ROLE_TYPE.
Note: If you set the user role to audience, the user cannot publish audio or video streams in the channel. If you want to publish media streams in a live broadcast, make sure to set the user role to broadcaster.
options
Detailed user options. See ClientRoleOptions.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -1: A general error occurs (no specific reason).
    • -2: Invalid parameter.
    • -5: The request is rejected.
    • -7: The SDK is not initialized.

updateChannelMediaOptions

Updates the media options of the channel after joining.

virtual int updateChannelMediaOptions(const ChannelMediaOptions& options) = 0;

Parameters

options
Channel media options. See ChannelMediaOptions.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: A value in ChannelMediaOptions is invalid, such as an invalid token or user ID. You need to provide valid parameters.
    • -7: The IRtcEngine object is not initialized. You need to initialize the IRtcEngine object before calling this method.
    • -8: The internal state of the IRtcEngine object is incorrect, possibly because the user has not joined the channel. It is recommended that you check whether the user is in the channel via the onConnectionStateChanged callback. If you receive a CONNECTION_STATE_DISCONNECTED (1) or CONNECTION_STATE_FAILED (5) state, it means the user is not in the channel. You need to call joinChannel to join the channel before calling this method.

updateChannelMediaOptionsEx

Updates channel media options after joining a channel.

virtual int updateChannelMediaOptionsEx(const ChannelMediaOptions& options, const RtcConnection& connection) = 0;

Scenario

This method applies to multi-channel scenarios.

Parameters

options
Channel media options. See ChannelMediaOptions.
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid member values in ChannelMediaOptions, such as an invalid token or user ID. You need to provide valid parameters.
    • -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.
    • -8: Internal state error of the IRtcEngine object, possibly because the user has not joined the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user is in the channel. If you receive CONNECTION_STATE_DISCONNECTED (1) or CONNECTION_STATE_FAILED (5), it means the user is not in the channel. You need to call joinChannel to join the channel before calling this method.

updatePreloadChannelToken

Updates the wildcard token used for preloaded channels.

virtual int updatePreloadChannelToken(const char* token) = 0;

You need to manage the lifecycle of the wildcard token yourself. When the token expires, generate a new wildcard token and call this method with the new token.

Scenario

Applicable to scenarios involving multiple channels. For example, when switching between different channels, using a wildcard token allows you to avoid requesting a new token each time a user joins a new channel, thereby saving channel switching time and reducing the load on your token server.

Parameters

token
The new wildcard token.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter, such as an invalid token. Please pass in valid parameters and rejoin the channel.
    • -7: The IRtcEngine object is not initialized. Please initialize the IRtcEngine object before calling this method.

onClientRoleChanged

Callback triggered when the user role or audience latency level changes.

virtual void onClientRoleChanged(CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole, const ClientRoleOptions& newRoleOptions)
Note: This callback is not triggered if you call setClientRole before joining the channel and set the user role to BROADCASTER.

Trigger Timing

This callback is triggered in any of the following cases:
  • After joining the channel, calling setClientRole to set the user role or audience latency level;
  • Before joining the channel, calling setClientRole and setting the user role to AUDIENCE.

Parameters

oldRole
The user role before the change. See CLIENT_ROLE_TYPE.
newRole
The user role after the change. See CLIENT_ROLE_TYPE.
newRoleOptions
The role options after the change. See ClientRoleOptions.
Note: Introduced since v4.1.0.

onClientRoleChangeFailed

Callback triggered when switching user roles fails.

virtual void onClientRoleChangeFailed(CLIENT_ROLE_CHANGE_FAILED_REASON reason, CLIENT_ROLE_TYPE currentRole)

This callback reports the reason for the failure to switch user roles and the current role.

Trigger Timing

When the local user fails to switch roles after joining the channel by calling setClientRole, the SDK triggers this callback.

Parameters

reason
The reason for the user role switch failure. See CLIENT_ROLE_CHANGE_FAILED_REASON.
currentRole
The current user role. See CLIENT_ROLE_TYPE.

onError

onError callback. Reports SDK runtime errors.

virtual void onError(int err, const char* msg)

This callback indicates that a network or media-related error occurred during SDK runtime. In most cases, the SDK cannot automatically recover, and you need to handle it at the application level or notify the user.

Parameters

err
Error code. See ERROR_CODE_TYPE.
msg
Error message.

onJoinChannelSuccess

Callback when the local user successfully joins a channel.

virtual void onJoinChannelSuccess(const char* channel, uid_t uid, int elapsed)

Trigger Timing

This callback is triggered when you call joinChannel, joinChannelWithUserAccount, joinChannelEx, or joinChannelWithUserAccountEx to join a channel.

Parameters

channel
Channel name.
uid
User ID of the local user.
elapsed
Time elapsed (ms) from calling joinChannel, joinChannelWithUserAccount, joinChannelEx, or joinChannelWithUserAccountEx to the callback being triggered.

onLocalUserRegistered

onLocalUserRegistered callback. Triggered when the local user registers a User Account.

virtual void onLocalUserRegistered(uid_t uid, const char* userAccount)

After the local user successfully calls registerLocalUserAccount to register a User Account, or calls joinChannelWithUserAccount to join a channel, the SDK triggers this callback and returns the local user's user ID and User Account.

Parameters

uid
The user ID of the local user.
userAccount
The User Account of the local user.

onRejoinChannelSuccess

onRejoinChannelSuccess callback.

virtual void onRejoinChannelSuccess(const char* channel, uid_t uid, int elapsed)

When the user is disconnected from the server due to network issues, the SDK automatically attempts to reconnect and triggers this callback upon success.

Trigger Timing

This callback is triggered when the SDK automatically reconnects after the user is disconnected from the server due to network issues.

Parameters

channel
Channel name.
uid
User ID of the user who rejoined the channel.
elapsed
Time elapsed (ms) from calling joinChannel to the callback being triggered.

onRenewTokenResult

renewToken method call result callback.

virtual void onRenewTokenResult(const char* token, RENEW_TOKEN_ERROR_CODE code)
Since
Added since v4.6.0.

This callback is triggered after you call the renewToken method to update the token, notifying the update result.

Parameters

token
Updated token.
code
Error code. See RENEW_TOKEN_ERROR_CODE.

onRequestToken

Callback triggered when the Token expires.

virtual void onRequestToken() {}
After receiving this callback, you need to generate a new Token on your Token server and update it using one of the following methods:
  • Single-channel scenario:
    • Call renewToken with the new Token.
    • Call leaveChannel to leave the current channel, then call joinChannel with the new Token.
  • Multi-channel scenario: Call updateChannelMediaOptionsEx with the new Token.

Trigger Timing

This callback is triggered when the Token expires.

onRtcStats

Reports statistics of the current call.

virtual void onRtcStats(const RtcStats& stats)

Trigger Timing

After the user joins the channel, the SDK triggers this callback every two seconds.

Parameters

stats
Statistics of the RTC engine. See RtcStats.

onTokenPrivilegeWillExpire

Callback triggered when the Token will expire in 30 seconds.

virtual void onTokenPrivilegeWillExpire(const char* token)
When you receive this callback, you need to generate a new Token on your Token server and update it using one of the following methods:
  • Single-channel scenario:
    • Call renewToken with the new Token.
    • Call leaveChannel to leave the current channel, then call joinChannel with the new Token.
  • Multi-channel scenario: Call updateChannelMediaOptionsEx with the new Token.

Trigger Timing

The SDK triggers this callback 30 seconds before the Token expires to remind you to update the Token.

Parameters

token
The Token that is about to expire.

onUserInfoUpdated

Callback triggered when the remote user's user ID and User Account are updated.

virtual void onUserInfoUpdated(uid_t uid, const UserInfo& info)

After a remote user joins the channel, the SDK obtains the user's user ID and User Account, caches them in a mapping table, and then triggers this callback on the local client.

Parameters

uid
The user ID of the remote user.
info
An object containing the remote user's user ID and User Account. See UserInfo.

onUserJoined

Callback triggered when a remote user or host joins the channel.

virtual void onUserJoined(uid_t uid, int elapsed)

In a communication channel, this callback indicates that a remote user has joined the channel. When the local user joins the channel, the SDK also triggers this callback to report the users already in the channel. In a live broadcast channel, this callback indicates that a host has joined the channel. When a host joins, the SDK also triggers this callback to report the hosts already in the channel. Agora recommends limiting the number of co-hosts to 32, with up to 17 video hosts supported.

Trigger Timing

The SDK triggers this callback under any of the following conditions:
  • A remote user or host joins the channel.
  • A remote user switches to the host role after joining the channel.
  • A remote user or host rejoins the channel after a network interruption.

Parameters

uid
The user ID of the user who joined the channel.
elapsed
The time delay (ms) from the local user calling joinChannel to this callback being triggered.

onUserOffline

onUserOffline callback: Triggered when a remote user (communication channel) or host (live broadcast channel) leaves the channel.

virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason)
A user going offline usually occurs in the following two scenarios:
  • Leaves the channel: When the user or host actively leaves the channel, a leave message is sent.
  • Drops offline: If no data packet is received from the user or host for a period of time, the SDK considers them offline. The timeout is 20 seconds in communication channels and longer in live broadcast channels. Poor network conditions may cause false positives. It is recommended to use the Agora RTM SDK for more reliable offline detection.

Trigger Timing

This callback is triggered when a remote user (communication channel) or host (live broadcast channel) leaves the channel.

Parameters

uid
The user ID of the user who left the channel or went offline.
reason
The reason why the user went offline. See USER_OFFLINE_REASON_TYPE.