joinChannel [2/2]

Joins a channel with media options.

public abstract int joinChannel(
      String token, String channelId, int uid, ChannelMediaOptions options);


This method enables users to join a channel. Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.

A successful call of this method triggers the following callbacks:

When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the onRejoinChannelSuccess callback on the local client.

Compared to joinChannel [1/2], this method adds the options parameter to configure whether to automatically subscribe to all remote audio and video streams in the channel when the user joins the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, giving rise to usage and billings. To unsubscribe, set the options parameter or call the mute methods accordingly.

  • This method allows users to join only one channel at a time.
  • Ensure that the app ID you use to generate the token is the same app ID that you pass in the create [2/2] method; otherwise, you may fail to join the channel by token.


The token generated on your server for authentication. See .
Note: If you need to join different channels at the same time or switch between channels, Agora recommends using a wildcard token so that you don't need to apply for a new token every time joining a channel. See Secure authentication with tokens.
The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
The user ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 232-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the onJoinChannelSuccess callback. Your application must record and maintain the returned user ID, because the SDK does not do so.
The channel media options. See ChannelMediaOptions.


  • 0: Success.
  • < 0: Failure.
    • -2: The parameter is invalid. For example, the token is invalid, the uid parameter is not set to an integer, or the value of a member in ChannelMediaOptions is invalid. You need to pass in a valid parameter and join the channel again.
    • -3: Failes to initialize the RtcEngine object. You need to reinitialize the RtcEngine object.
    • -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method.
    • -8: The internal state of the RtcEngine object is wrong. The typical cause is that you call this method to join the channel without calling startEchoTest [3/3] to stop the test after calling stopEchoTest to start a call loop test. You need to call stopEchoTest before calling this method.
    • -17: The request to join the channel is rejected. The typical cause is that the user is in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. Do not call this method to join the channel unless you receive the CONNECTION_STATE_DISCONNECTED(1) state.
    • -102: The channel name is invalid. You need to pass in a valid channelname in channelId to rejoin the channel.
    • -121: The user ID is invalid. You need to pass in a valid user ID in uid to rejoin the channel.