Server SDK API BetaAgora Signaling SDK Error Codes

Server SDK API Beta

The Server SDK API includes the following classes:

Class Description
Signal Class Basic Signal class.
LoginSession Class Internal class of Signal Class; Creates a LoginSession object when the login() method of Signal Class is called.
Channel Class Internal class of Signal Class; Creates a Channel object when the channelJoind() method of the LoginSession object is called.
Call Class Internal class of Signal Class; Creates a Call object when the channelInviteUser2() method of the LoginSession object is called.
LoginCallback Class Internal class of Signal Class; Manages login-related callbacks.
MessageCallback Class Internal class of Signal Class; Manages message-related callbacks.
ChannelCallback Class Internal class of Signal Class; Manages channel-related callbacks.
CallCallback Class Internal class of Signal Class; Manages call-related callbacks.

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

Note

Please avoid using synchronization or block when it comes to callback operations. Otherwise, the signaling system may crash.

Signal Class

Signal Class is the basic class of signaling.

Methods

Create Signal Object (Signal)

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

Enable Debug Log (setDoLog)

public void setDoLog(boolean doLog)
Parameter Description
doLog
  • 1: Enable debug log
  • 0: Disable debug log

Login (login)

public Signal.LoginSession login(String account, String token, Signal.LoginCallback cb)

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

Parameter Description
account User ID defined by the client. Maximum length is 128 visible characters (space not permitted). Can be the uid, nickname, guid or any other content as long as it is unique. The same applies hereafter.
token Signaling Key generated from App ID and App Certificate. See signaling_key for details.
cb LoginCallback instance object.

Note

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.

LoginSession Class

Internal class of Signal Class; Creates a LoginSession object when the login() method of Signal Class is called.

Methods

Log out (logout)

public void logout();

This method triggers the onLogout callback upon a successful execution.

Send Point-to-Point Message (messageInstantSend)

public void messageInstantSend(String account, String msg, Signal.MessageCallback cb)

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

Parameter Description
account User ID defined by the client.
msg The message body. Maximum length is 8K visible characters.
cb MessageCallback instance object.

Send Point-to-Point Message (messageInstantSend)

public void messageInstantSend(String account, String msg, int ttl, Signal.MessageCallback cb)

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

Parameter Description
account User ID defined by the client.
msg The message body. Maximum length is 8K visible characters.
ttl Time-to-live.
cb MessageCallback instance object.

Initiate a Call (channelInviteUser2)

public Signal.LoginSession.Call channelInviteUser2(String channel, String peer, String extra, final Signal.CallCallback cb)

This method initiates a call, i.e., inviting other user to join a specific channel. Caling and joining channel are 2 separate processes.

Parameter Description
channel Channel name. Maximum length is 128 visible characters.
peer Account of the other user.
extra Additional information about the call. Can be a string, a JSON string or NULL.
cb CallCallback instance object.

Join Channel (channelJoin)

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

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

Parameter Description
channelID

The channel name. It can be up to 128 visible characters. It has the following two built-in attributes:

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

Note

The above 2 channel names are to be used by servers only. Joining these channels to receive login events and channel events, etc.

Channel Class

Internal class of Signal Class; Creates a Channel object when the channelJoind() method of the LoginSession object is called.

Methods

Leave Channel (channelLeave)

public void channelLeave()

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

Set Channel Attributes (channelSetAttr)

public void channelSetAttr(String name, String value)

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

Parameter Description
name The attribute name. Maximum length is 128 visible characters.
value The attribute value. Maximum length is 8096 visible characters.

Following are the in-built 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 The time (in seconds) between the last user leaves a channel and the system destroys it. The default value is 7200. A special channel will never be destroyed.
_member_num The number of the users current in the channel. Is updated automatically by the system.
_auto_update_num

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

  • 0: Disabled (default)
  • 1~n: The refreshing frequency in seconds.

Delete Channel Attributes (channelDelAttr)

public void channelDelAttr(String name)

This method deletes a specific attribute of the current channel.

Parameter Description
name The attribute name. Maximum length is 128 visible characters.

Delete All Channel Attributes (channelClearAttr)

public void channelClearAttr()

This method deletes all the attributes of the current channel.

Send Channel Message (messageChannelSend)

public void messageChannelSend(String msg)

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

Parameter Description
msg The message body. In a large group call, each message must not exceed 8K 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

Internal class of Signal Class; Creates a Call object when the channelInviteUser2() method of the LoginSession object is called.

Methods

Accept Call (channelInviteAccept)

public void channelInviteAccept()

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

Accept Call (channelInviteAccept)

public void channelInviteAccept(String extra)

This method accepts the received call request/invitation.

Parameter Description
extra Additional Information the caller wants to deliver to the callee, e.g., specifying if it is a video or audio call. Must be in JSON format.

Reject Call (channelInviteRefuse)

public void channelInviteRefuse()

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

Reject Call (channelInviteRefuse)

public void channelInviteRefuse(String extra)

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

Parameter Description
extra Additional Information the caller wants to deliver to the callee, e.g., specifying if it’s a video or audio call. Must be in JSON format.

End Call (channelInviteEnd)

public void channelInviteEnd(String extra)

This method ends the call. The user himself/herself receives the onInviteEndByMyself event, and the other user receives onInviteEndByPeer event.

Parameter Description
extra Additional Information the caller wants to deliver to the callee, e.g., specifying if it’s a video or audio call. Must be in JSON format.

End Call (channelInviteEnd)

public void channelInviteEnd()

This method ends the call. The user himself/herself receives the onInviteEndByMyself event, and the other user receives onInviteEndByPeer event.

LoginCallback Class

Internal class of Signal Class; Manages login-related callbacks.

Callbacks

User Online Callback (onLoginSuccess)

public void onLoginSuccess(Signal.LoginSession session, int uid)

This callback is triggered when the user logs on to the Agora signaling system.

Parameter Description
session The sesssion name.
uid The internal User ID generated automatically by the sytem.

User Offline Callback (onLogout)

public void onLogout(Signal.LoginSession session, int ecode)

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

Parameter Description
session The sesssion name.
ecode The error code.

User Login Failed Callback (onLoginFailed)

public void onLoginFailed(Signal.LoginSession session, int ecode)

This callback is triggered when the user fails to log into the Agora signaling system.

Parameter Description
session The sesssion name.
ecode The error code.

Other User Received Message Callback (onMessageInstantReceive)

public void onMessageInstantReceive(Signal.LoginSession session, String account, int uid, String msg)

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

Parameter Description
session The sesssion name.
account User ID defined by the client.
uid The internal User ID generated automatically by the system.
msg The message body.

Call Invitation Received Callback (onInviteReceived)

public void onInviteReceived(Signal.LoginSession session, Signal.LoginSession.Call call)

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

Parameter Description
session The session name.
call The call instance object.

Error Reported Callback (onError)

public void onError(Signal.LoginSession session, int ecode, String reason)

This callback is triggered when an error is detected.

Parameter Description
session The session name.
ecode The error code.
reason The reason why the error occurs.

MessageCallback Class

Internal class of Signal Class; Manages message-related callbacks.

Callbacks

Message Sent Callback (onMessageSendSuccess)

public void onMessageSendSuccess(Signal.LoginSession session)

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

Parameter Description
session The session name.

Message Failure Callback (onMessageSendError)

public void onMessageSendError(Signal.LoginSession session, int ecode)

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

Parameter Description
session The session name.
ecode The error code.

ChannelCallback Class

Internal class of Signal Class; Manages channel-related callbacks.

Callbacks

User Joined Channel Callback (onChannelJoined)

public void onChannelJoined(Signal.LoginSession session, Signal.LoginSession.Channel channel)

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

Parameter Description
session The session name.
channel The channel Name.

User Failed to Join Channel Callback (onChannelJoinFailed)

public void onChannelJoinFailed(Signal.LoginSession session, Signal.LoginSession.Channel channel, int ecode)

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

Parameter Description
session The session name.
channel The channel Name.
ecode The error code.

User Left Channel Callback (onChannelLeaved)

public void onChannelLeaved(Signal.LoginSession session, Signal.LoginSession.Channel channel, int ecode)

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

Parameter Description
session The session name.
channel The channel Name.
ecode The error code.

Other User Joined Channel Callback (onChannelUserJoined)

public void onChannelUserJoined(Signal.LoginSession session, Signal.LoginSession.Channel channel, String account, int uid);

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

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)

public void onChannelUserLeaved(Signal.LoginSession session, Signal.LoginSession.Channel channel, String account, int uid)

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

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.

User List Received Callback (onChannelUserList)

public void onChannelUserList(Signal.LoginSession session, Signal.LoginSession.Channel channel, List<String> users, List<Integer> uids)

This callback is triggered when the user has joined a non-large channel (i.e., less than 200 people).

Parameter Description
session The session name.
channel The channel Name.
users The list of user accounts used to log onto the App.
uid The internal User ID generated automatically by the system.

Channel Attribute Changed Callback (onChannelAttrUpdated)

public void onChannelAttrUpdated(Signal.LoginSession session, Signal.LoginSession.Channel channel, String name, String value, String type)

This callback is triggered when the channel attribute is changed.

Parameter Description
session The session name.
channel The channel Name.
name The name of the attribute.
value The value of the attribute.
type The type of the attribute.

Channel Message Received Callback (onMessageChannelReceive)

public void onMessageChannelReceive(Signal.LoginSession session, Signal.LoginSession.Channel channel, String account, int uid, String msg)

This callback is trigged upon receiving the channel message.

Parameter Description
session The session name.
channel The channel Name.
account The account of the other user defined by the client.
msg The message body.

CallCallback Class

Internal class of Signal Class; Manages call-related callbacks.

Callbacks

Other User Received Call Callback (onInviteReceivedByPeer)

public void onInviteReceivedByPeer(Signal.LoginSession session, Signal.LoginSession.Call call)

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

Parameter Description
session The session Name.
call The call object itself.

Other User Accepted Call Callback (onInviteAcceptedByPeer)

public void onInviteAcceptedByPeer(Signal.LoginSession session, Signal.LoginSession.Call call, String extra)

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

Parameter Description
session The session name.
call The call object itself.
extra Additional Information the caller wants to deliver to the callee, e.g., specifying if it’s a video or audio call. Must be in JSON format.

Other User Rejected Call (onInviteRefusedByPeer)

public void onInviteRefusedByPeer(Signal.LoginSession session, Signal.LoginSession.Call call, String extra)

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

Parameter Description
session The session name.
call The call object itself.
extra Additional Information the caller wants to deliver to the callee, e.g., specifying if it’s a video or audio call. Must be in JSON format.

Call Failed Callback (onInviteFailed)

public void onInviteFailed(Signal.LoginSession session, Signal.LoginSession.Call call, int ecode)

This callback is triggered when a call fails.

Parameter Description
session The session name.
call The call object itself.
extra Additional Information the caller wants to deliver to the callee, e.g., specifying if it’s a video or audio call. Must be in JSON format.

Other User Ended Call Callback (onInviteEndByPeer)

public void onInviteEndByPeer(Signal.LoginSession session, Signal.LoginSession.Call call, String extra)

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

Parameter Description
session The session name.
call The call object itself.
extra Additional Information the caller wants to deliver to the callee, e.g., specifying if it’s a video or audio call. Must be in JSON format.

Call Ended Callback (onInviteEndByMyself)

public void onInviteEndByMyself(Signal.LoginSession session, Signal.LoginSession.Call call, String extra)

This callback is triggered when the user ended the call.

Message Received Callback (onInviteMsg)

public void onInviteMsg(Signal.LoginSession session, Signal.LoginSession.Call call, String extra)

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

Parameter Description
session The session name.
call The call object itself.
extra Additional Information the caller wants to deliver to the callee. Must be in JSON format.

Agora Signaling SDK Error Codes

Introduction

The Agora Signaling SDK will return error or warning codes when calling APIs or during runtime:

  • Error Codes occur when the SDK encountered an error that can be not recovered automatically without any application intervention.
  • Warning Codes occur when the SDK encountered an error that might be recovered automatically. A Warning Code is just for notification, which can usually be ignored.
Error Code Value Description
SUCCESS 0 No error.
LOGOUT_E_OTHER 100 Logout due to reasons such as network issues.
LOGOUT_E_USER 101 A user logged out.
LOGOUT_E_NET 102 A network issue.
LOGOUT_E_KICKED 103 The account is logged in another place.
LOGOUT_E_PACKET 104 This error code is obsolete.
LOGOUT_E_TOKENEXPIRED 105 The Signaling Key expired.
LOGOUT_E_OLDVERSION 106 This error code is obsolete.
LOGOUT_E_TOKENWRONG 107 This error code is obsolete.
LOGIN_E_OTHER 200 An unknown reason.
LOGIN_E_NET 201 A network issue.
LOGIN_E_FAILED 202 The login was rejected by the server.
LOGIN_E_CANCEL 203 The user cancelled the login.
LOGIN_E_TOKENEXPIRED 204 The Signaling Key expired, and the login was rejected.
LOGIN_E_OLDVERSION 205 This error code is obsolete.
LOGIN_E_TOKENWRONG 206 The Signaling Key is invalid, see error_206 for details.
LOGIN_E_TOKEN_KICKED 207 The user used a renewed Signaling Key to login another place.
LOGIN_E_ALREADY_LOGIN 208 The user has already logged in. You can ignore this error.
JOINCHANNEL_E_OTHER 300 Failed to join a channel.
SENDMESSAGE_E_OTHER 400 Failed to send message.
SENDMESSAGE_E_TIMEOUT 401 A timeout in sending a message.
QUERYUSERNUM_E_OTHER 500 Failed to query the channel user number.
QUERYUSERNUM_E_TIMEOUT 501 A timeout in querying the channel user number.
QUERYUSERNUM_E_BYUSER 501 This error code is obsolete.
LEAVECHANNEL_E_OTHER 600 The user left the channel due to an unknown reason.
LEAVECHANNEL_E_KICKED 601 The user was kicked out by the administrator.
LEAVECHANNEL_E_BYUSER 602 The user has left the channel.
LEAVECHANNEL_E_LOGOUT 603 The user was kicked out of the channel upon logout.
LEAVECHANNEL_E_DISCONN 604 The user left the channel due to a network outage.
INVITE_E_OTHER 700 The call failed.
INVITE_E_REINVITE 701 Repeated calls.
INVITE_E_NET 702 A network issue.
INVITE_E_PEEROFFLINE 703 The other user is offline
INVITE_E_TIMEOUT 704 A call timeout.
INVITE_E_CANTRECV 705 This error code is obsolete.
GENERAL_E 1000 A general error.
GENERAL_E_FAILED 1001 A general error: Failure.
GENERAL_E_UNKNOWN 1002 A general error: Unknown.
GENERAL_E_NOT_LOGIN 1003 A general error: An action before login.
GENERAL_E_WRONG_PARAM 1004 A general error: A parameter call error.