Version: v1.4.0 BETA

The Server SDK API includes the following classes:

Class Description
Signaling Class Basic Signaling class.
LoginSession Class An internal class of the Signaling Class that creates a LoginSession object when the login method of the Signaling Class is called.
Channel Class An internal class of the Signaling Class that creates a Channel object when the channelJoind method of the LoginSession object is called.
Call Class An internal class of the Signaling Class that creates a Call object when the channelInviteUser2 method of the LoginSession object is called.
UserAttrCallback Class An internal class of the Signaling Class that manages user-attribute-related callbacks.
LoginCallback Class An internal class of the Signaling Class that manages login callbacks.
MessageCallback Class An internal class of the Signaling Class that manages message callbacks.
ChannelCallback Class An internal class of the Signaling Class that manages channel callbacks.
CallCallback Class An internal class of the Signaling Class that manages call callbacks.

Unlike other Signaling APIs, the Server SDK APIs allow multiple signaling objects (instances). Although each signaling instance can include multiple sessions, for now, only one instance allows you to join one channel only.

Avoid using synchronous or block callback operations. Otherwise, the signaling system may crash.

Signaling Class

The Signaling Class is the basic class of signaling.

Methods

Create a Signaling Object (Signal)

This method creates a signaling object.

public Signal(String appid)
Parameter Description
appid App account provided by Agora. See Get an App ID for details.

Enable a Debug Log (setDoLog)

This method enables a debug log.

public void setDoLog(boolean doLog)
Parameter Description
doLog
  • True: Enable debug log
  • False: Disable debug log

Login (login)

This method allows you to login Agora’s signaling system and it returns a LoginSession instance object. You must login before performing any action.

public Signal.LoginSession login(String account, String token, Signal.LoginCallback cb)
Parameter Description
account User ID defined by the client. Maximum length is 128 visible characters (space not permitted). Can be a uid, nickname, guid, or any other content that is unique.
token SignalingToken generated from the App ID and App Certificate. See How to Get and Use a SignalingToken for details.
cb LoginCallback instance object.

You can skip the generation of the token in a test environment by setting token to _no_need_token. Agora does not recommend doing so in a production environment. By default, if you are already logged in, the call of login will be ignored. To cancel the previous login, call logout beforehand without having to wait until it is successfully executed.

Set a User Attribute (userSetAttr)

This method sets a specified attribute of a user.

public void userSetAttr(String name, String value, final Signal.UserAttrCallback cb)
Parameter Description
name Attribute name
value Attribute value
cb Signal.UserAttrCallback instance

Get a User Attribute (userGetAttr)

This method gets a specified attribute of a user. A UserAttrCallback instance object is returned.

public void userGetAttr(String account, String name, final Signal.UserAttrCallback cb)
Parameter Description
account User account
name Attribute name
cb Signal.UserAttrCallback instance

Get all the User Attributes (userGetAttrAll)

This method gets all the attributes of a user. A UserAttrCallback instance object is returned.

public void userGetAttrAll(String account, final Signal.UserAttrCallback cb)
Parameter Description
account User account
cb Signal.UserGetAttrCallback instance

Query the Number of Users in a Channel (channelQueryUserNum)

This method gets the number of users in a channel. A UserAttrCallback instance object is returned.

public void channelQueryUserNum(String name, final Signal.UserAttrCallback cb)
Parameter Description
name Channel name
cb Signal.UserAttrCallback instance

Get the Current Status (getStatus)

This method gets the current login status. The following table shows the relationship between the return value and the login status:

public int getStatus()
Return Value Login Status
0 Not logged in/Logged out
1 Connecting/Logging in
2 Logged in
3 Login failed

LoginSession Class

An internal class of the Signaling Class that creates a LoginSession object when the login method of the Signaling Class is called.

Methods

Logout (logout)

This method triggers the onLogout callback upon a successful execution.

public void logout();

Send a Point-to-point Message (messageInstantSend)

This method sends a point-to-point message to a specified account.

public void messageInstantSend(String account, String msg, Signal.MessageCallback cb)
Parameter Description
account User ID defined by the client.
msg The message body. Maximum length is 8-k visible characters.
cb MessageCallback instance object.

Send a Point-to-Point Message (messageInstantSend)

This method sends a point-to-point message to a specified account.

public void messageInstantSend(String account, String msg, int ttl, Signal.MessageCallback cb)
Parameter Description
account User ID defined by the client.
msg Message body. Maximum length is 8-k visible characters.
ttl Time-to-live.
cb MessageCallback instance object.

Initiate a Call (channelInviteUser2)

This method initiates a call, such as inviting another user to join a specific channel. Calling and joining a channel are two different processes.

public Signal.LoginSession.Call channelInviteUser2(String channel, String peer, String extra, final Signal.CallCallback cb)
Parameter Description
channel Channel name. Maximum length is 128 visible characters.
peer Account of the other user.
extra

Extra information that the caller wants to send to the callee. It can be up to 8 KB visible characters and must be in JSON format. For example:

  • {“_require_peer_online”:1} If the counterpart is offline, the onInviteFailed callback will be triggered immediately.
  • {“_require_peer_online”:0} If the counterpart is offline for more than 20 seconds, the onInviteFailed callback will be triggered (default).
  • {“destMediaUid” : 123} Specify the uid for joining the corresponding media channel.
  • {“srcNum” : “+123456789”} Specify the phone number to be displayed on the screen of the remote phone.
<
cb CallCallback instance object.

You do not need to set the _require_peer_online field when making a SIP call.

Join a Channel (channelJoin)

This method allows a user to join a specified channel. Whenever he/she joins a specified channel, he/she will be disconnected from any previously joined channel.

public Signal.LoginSession.Channel channelJoin(String name, Signal.ChannelCallback cb)
Parameter Description
name

Channel name. It can be up to 128 visible characters and include the following special channel names and attributes:

  • _agora_user_online: All user-online or user-offline events within the current appID will be sent to this channel.
  • _agora_channel_event: All events about a user joining or leaving a channel within the current appID will be sent to this channel.
cb ChannelCallback instance object.

Special channels are used by servers only to receive login and channel events.

Channel Class

An internal class of the Signaling Class that creates a Channel object when the channelJoin method of the LoginSession object is called.

Methods

Leave a Channel (channelLeave)

This method allows a user to leave a channel. Once the user has left the channel, all other users in the channel receive the onChannelUserLeaved callback.

public void channelLeave()

Set the Channel Attributes (channelSetAttr)

This method sets the channel attributes. Whenever a change is made on an attribute, all users in the channel receive the onChannelAttrUpdated callback.

public void channelSetAttr(String name, String value)
Parameter Description
name Attribute name. Maximum length is 128 visible characters.
value Attribute value. Maximum length is 8096 visible characters.

The following table shows the built-in attributes of the parameter, name:

Attributes Description
_userNotification
  • 1: Default value. The channel sends callbacks that a user has joined or left the channel.
  • 0: The channel does not send callbacks that a user has joined or left the channel.
_channel_ttl Time (s) between the last user leaving a channel and the system destroying the channel. The default value is 7200. A special channel will never be destroyed.
_member_num Number of the users currently in the channel. It is automatically updated by the system.
_auto_update_num

Indicates whether to automatically refresh the number of the users currently in the channel.

  • 0: Disabled (default)
  • 1 - n: Refreshing frequency (s)
_total_member_num Automatically indicates the accumulated number of the users in the channel. Similar to _member_num , _auto_update_num and _auto_update_total_num both need to be set to none zero.
_auto_update_total_num

Indicates whether to automatically refresh the number of the users currently in the channel.

  • 0: (Default) Disabled
  • 1 - n: Refreshing frequency (s) (same as _auto_update_num )
_sendmsg_limit Maximum messages allowed to be sent in the channel.
_setattr_limit Maximum times for updating a channel attribute in a second.

Delete a Channel Attribute (channelDelAttr)

This method deletes a specific attribute of the current channel.

public void channelDelAttr(String name)
Parameter Description
name Attribute name. Maximum length is 128 visible characters.

Delete all Channel Attributes (channelClearAttr)

This method deletes all attributes of the current channel.

public void channelClearAttr()

Send a Channel Message (messageChannelSend)

This method sends a channel message to all users in the same channel.

public void messageChannelSend(String msg)
Parameter Description
msg Message body. Each channel message must not exceed 8 k visible characters. A user cannot send more than 60 messages per second, and the entire channel can not send more than 1,000 messages per second.

Call Class

An internal class of the Signaling Class that creates a Call object when the channelInviteUser2 method of the LoginSession object is called.

Methods

Accept a Call (channelInviteAccept)

This method accepts the received call request/invitation. The caller will receive the onInviteAcceptedByPeer callback.

public void channelInviteAccept()

Accept a Call (channelInviteAccept)

This method accepts the received call request/invitation.

public void channelInviteAccept(String extra)
Parameter Description
extra Extra information the caller wants to deliver to the callee. For example, specifying if it is a video or voice call. Must be in JSON format. Can be “”.

Reject a Call (channelInviteRefuse)

This method rejects the received call invitation/request. Once this API is called, the other user will receive the onInviteRefusedByPeer event.

public void channelInviteRefuse()

Reject a Call (channelInviteRefuse)

This method rejects the received call invitation/request. Once this API is called, the other user will receive the onInviteRefusedByPeer event.

public void channelInviteRefuse(String extra)
Parameter Description
extra Extra information the caller wants to deliver to the callee. For example, specifying if it is a video or voice call. Must be in JSON format.

End a Call (channelInviteEnd)

This method ends a call. The user receives the onInviteEndByMyself event, and the other user receives the onInviteEndByPeer event.

public void channelInviteEnd(String extra)
Parameter Description
extra Extra information the caller wants to deliver to the callee. For example, specifying if it is a video or voice call. Must be in JSON format.

End a Call (channelInviteEnd)

This method ends a call. The user receives the onInviteEndByMyself event, and the other user receives the onInviteEndByPeer event.

public void channelInviteEnd()

UserAttrCallback Class

An internal class of the Signaling Class that manages user attribute callbacks.

Callbacks

Get the User Attribute Callback (onUserGetAttr)

This callback is triggered when getting the user attribute.

public void onUserGetAttr(String err, JSONObject ret)
Parameter Description
err Error information. An empty string means that there is no error.
ret
  • Success: {“result”: “ok”, “account”: “user account”, “name”: “attr name”, “value”: “attr value”}
  • Failure: {“result”: “failed”, “reason”: “failed reason”}

Get all the User Attributes Callback (onUserGetAttrAll)

This callback is triggered when getting all the attributes of a user.

public void onUserGetAttrAll(String err, JSONObject ret)
Parameter Description
err Error information. An empty string means that there is no error.
ret
  • Success: {“result”: “ok”, “account”: “user account”, “json”: {“attr 1” : “value 1”, “attr 2” : “value2”}
  • Failure: {“result”: “failed”, “reason”: “failed reason”}

Set the User Attribute Callback (onUserSetAttr)

This callback is triggered when setting an attribute of a user.

public void onUserSetAttr(String err, JSONObject ret)
Parameter Description
err Error information. An empty string means that there is no error.
ret
  • Success: {“result”: “ok”, “reason”: “”}
  • Failure: {“result”: “failed”, “reason”: “failed reason”}

LoginCallback Class

An internal class of the Signaling Class that manages login-related callbacks.

Callbacks

User Online Callback (onLoginSuccess)

This callback is triggered when a user is logged in the Agora signaling system.

public void onLoginSuccess(Signal.LoginSession session, int uid)
Parameter Description
session Session name.
uid Internal User ID generated by the system.

User Offline Callback (onLogout)

This callback is triggered when a user has logged out of the Agora signaling system.

public void onLogout(Signal.LoginSession session, int ecode)
Parameter Description
session Session name.
ecode Error code.

User Login Failed Callback (onLoginFailed)

This callback is triggered when a user fails to login the Agora signaling system.

public void onLoginFailed(Signal.LoginSession session, int ecode)
Parameter Description
session Session name.
ecode Error code.

Message Received Callback (onMessageInstantReceive)

This callback notifies a user that he/she has received a message.

public void onMessageInstantReceive(Signal.LoginSession session, String account, int uid, String msg)
Parameter Description
session Session name.
account User ID defined by the client.
uid Internal User ID generated by the system.
msg Message body.

Call Invitation Received Callback (onInviteReceived)

This callback is triggered when a user has received a call invitation/request.

public void onInviteReceived(Signal.LoginSession session, Signal.LoginSession.Call call)
Parameter Description
session Session name.
call Call instance object.

Error Reported Callback (onError)

This callback is triggered when an error is detected.

public void onError(Signal.LoginSession session, int ecode, String reason)
Parameter Description
session Session name.
ecode Error code. For more information, see Error Codes and Warning Codes.
reason Reason why the error occurred.

MessageCallback Class

An internal class of the Signaling Class that manages message-related callbacks.

Callbacks

Message Sent Callback (onMessageSendSuccess)

This callback is triggered when a user has sent a message.

public void onMessageSendSuccess(Signal.LoginSession session)
Parameter Description
session Session name.

Message Failure Callback (onMessageSendError)

This callback is triggered when a user fails to send a message.

public void onMessageSendError(Signal.LoginSession session, int ecode)
Parameter Description
session Session name.
ecode Error code.

ChannelCallback Class

An internal class of the Signaling Class that manages channel-related callbacks.

Callbacks

User Joined Channel Callback (onChannelJoined)

This callback is triggered when a user has joined a channel.

public void onChannelJoined(Signal.LoginSession session, Signal.LoginSession.Channel channelName)
Parameter Description
session Session name.
channel Channel name.

User Failed to Join Channel Callback (onChannelJoinFailed)

This callback is triggered when a user has failed to join a channel.

public void onChannelJoinFailed(Signal.LoginSession session, Signal.LoginSession.Channel channel, int ecode)
Parameter Description
session Session instance.
channel Channel instance.
ecode Error code.

User Left Channel Callback (onChannelLeaved)

This callback is triggered when the user has left a channel.

public void onChannelLeaved(Signal.LoginSession session, Signal.LoginSession.Channel channel, int ecode)
Parameter Description
session Session name.
channel Channel name.
ecode Error code.

Other User Joined Channel Callback (onChannelUserJoined)

This callback is triggered when another user has joined the channel.

public void onChannelUserJoined(Signal.LoginSession session, Signal.LoginSession.Channel channel, String account, int uid);
Parameter Description
session The session name.
channel The channel Name.
account The account of the other user defined by the client.
uid The internal User ID generated automatically by the system.

Other User Left Channel Callback (onChannelUserLeaved)

This callback is triggered when a user has left the channel.

public void onChannelUserLeaved(Signal.LoginSession session, Signal.LoginSession.Channel channel, String account, int uid)
Parameter Description
session Session name.
channel Channel name.
account Account of the other user defined by the client.
uid Internal user ID generated by the system.

User List Received Callback (onChannelUserList)

A user will receive this callback when he/she has joined a channel.

Note:

The retrieved user list includes a maximum of 200 users latest in the channel.

public void onChannelUserList(Signal.LoginSession session, Signal.LoginSession.Channel channel, List<String> users, List<Integer> uids)
Parameter Description
session Session name.
channel Channel name.
users List of user accounts used to login the app.
uid List of users in the channel.

Channel Attribute Changed Callback (onChannelAttrUpdated)

This callback is triggered when a channel attribute is changed.

public void onChannelAttrUpdated(Signal.LoginSession session, Signal.LoginSession.Channel channel, String name, String value, String type)
Parameter Description
session Session name.
channel Channel name.
name Name of the attribute.
value Value of the attribute.
type Type of the attribute.

Query the Number of Users in a Channel Callback (onChannelQueryUserNum)

This callback is triggered when the number of users in a channel is queried.

public void onChannelQueryUserNum(Signal.LoginSession session, String err, int num)
Parameter Description
session Session name.
channel Channel name.
name Name of the attribute.
value Value of the attribute.
type Type of the attribute.

Channel Message Received Callback (onMessageChannelReceive)

This callback is trigged upon receiving the channel message.

public void onMessageChannelReceive(Signal.LoginSession session, Signal.LoginSession.Channel channel, String account, int uid, String msg)
Parameter Description
session Session name.
channel Channel name.
account Account of the other user defined by the client.
uid Internal user ID generated by the system.
msg Message body.

CallCallback Class

An internal class of the Signaling Class that manages call-related callbacks.

Callbacks

Other User Received Call Callback (onInviteReceivedByPeer)

This callback is triggered when the callee has received a call invitation/request.

public void onInviteReceivedByPeer(Signal.LoginSession session, Signal.LoginSession.Call call)
Parameter Description
session Session name.
call Call object.

Other User Accepted Call Callback (onInviteAcceptedByPeer)

This callback is triggered when the callee has accepted a call invitation/request.

public void onInviteAcceptedByPeer(Signal.LoginSession session, Signal.LoginSession.Call call, String extra)
Parameter Description
session Session name.
call Call object.
extra Extra information the caller wants to deliver to the callee. For example, specifying if it is a video or voice call. Must be in JSON format.

Other User Rejected Call (onInviteRefusedByPeer)

This callback is triggered when the callee has rejected a call invitation/request.

public void onInviteRefusedByPeer(Signal.LoginSession session, Signal.LoginSession.Call call, String extra)
Parameter Description
session Session name.
call Call object.
extra Extra information the caller wants to deliver to the callee. For example, specifying if it is a video or voice call. Must be in JSON format.

Call Failed Callback (onInviteFailed)

This callback is triggered when a call fails.

public void onInviteFailed(Signal.LoginSession session, Signal.LoginSession.Call call, int ecode)
Parameter Description
session Session name.
call Call object.
extra Extra information the caller wants to deliver to the callee. For example, specifying if it is a video or voice call. Must be in JSON format.

Other User Ended Call Callback (onInviteEndByPeer)

This callback is triggered when the callee has ended the call.

public void onInviteEndByPeer(Signal.LoginSession session, Signal.LoginSession.Call call, String extra)
Parameter Description
session Session name.
call Call object.
extra Extra information the caller wants to deliver to the callee. For example, specifying if it is a video or voice call. Must be in JSON format.

Call Ended Callback (onInviteEndByMyself)

This callback is triggered when the user ended the call.

public void onInviteEndByMyself(Signal.LoginSession session, Signal.LoginSession.Call call, String extra)
Parameter Description
session Session name.
call Call object.
extra Extra information the caller wants to deliver to the callee. For example, specifying if it is a video or voice call. Must be in JSON format.

Message Received Callback (onInviteMsg)

This callback is triggered when the user has received a DTMF message from the other user.

public void onInviteMsg(Signal.LoginSession session, Signal.LoginSession.Call call, String extra)
Parameter Description
session Session name.
call Call object.
extra Extra information the caller wants to deliver to the callee. Must be in JSON format.

Error Codes and Warning Codes

See Error Codes and Warning Codes.