Version: v1.4.0 BETA

The Signaling Web API consists of the following objects, with each object having its own methods and callback functions:

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

Signal

Obtain a signal object:

signal = Signal(appid)
Parameter Description
appid The App ID of the project. See Get an App ID for details on how to obtain an App ID.

Methods

Log into Agora's Signaling System (login)

Use this method to log into Agora’s signaling system and it returns a session. You can execute message, channel, and call operations, as well as set callback functions in that session.

login(account, token, reconnect_count, reconnect_time) : Session
  • When login is successful, the onLoginSuccess callback function is triggered,
  • When login fails, the onLoginFailed callback function is triggered,
  • When the SDK loses connection with the server, the onLogout callback function is triggered.
Parameter Description
account User ID defined by the client. Maximum length is 128 visible characters (space not allowed). 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.
reconnect_count The maximum attempts allowed to reconnect to the server (10 by default).
reconnect_time The maximum time allowed to reconnect to the server (30 s by default).

You can skip generating the token in a test environment by setting token to _no_need_token. However, Agora does not recommend this in a production environment. By default, if you are already logged in, the login call will be ignored. To cancel the previous login, call logout first without having to wait until it is successfully executed. The system will stop reconnecting to the server, if either reconnect_count or reconnect_time is reached.

Sets the System Log（setDoLog）

setDolog(isEnabled, level)

This method sets the system log.

Parameter Description
isEnabled

Whether to print the system log.

  • true: Print the system log.
  • false: (Default) Do not print the system log.
level

Sets the level of the system log.

  • DEBUG (default)
  • WARNING
  • INFO

Retrieves the Login Status (getStatus)

This method retrieves the login status and is synchronous. The return value indicates the current login status.

getStatus() : Integer

The following table shows the relationship between the return value and the login status.

Return Value Login Status
0 Not logged in/Logged out.
1 Connecting/Logging in.
2 Logged in.

Retrieves the SDK Version (getSDKVersion)

This method retrieves the SDK version and is synchronous. The return value is a string containing the SDK version, such as ‘1.3.0’.

getSDKVersion() : String

Session

Methods

Remote Calling Process (invoke)

This method is used for the remote calling process and triggers the onInvokeRet callback function when called successfully.

invoke(func, args, cb)
Function Parameter Settings and Returns
Queries the user status.
  • name: io.agora.signal.user_query_user_status
  • req: {“account”:account of the user}
  • Returns: status(1:online; 0:offline)
Sets a user attribute.
  • name: io.agora.signal.user_set_attr
  • req: {“name”:attribute name,”value”:attribute value}
Retrieves a user attribute.
  • name: io.agora.signal.user_get_attr
  • req: {“account”:account of the user,”name”:attribute name}
  • Returns: {“value”:attribute value}
Retrieves all attributes of a user.
  • name: io.agora.signal.user_get_attr_all
  • req: {“account”:account of the user}
  • Returns: The JSON value of all attributes
Retrieves the number of the users in a channel.
  • name: io.agora.signal.channel_query_num
  • req: {“name”:channel name}
  • Returns: All users in the channel
Checks if a user is in a specific channel.
  • name: io.agora.signal.channel_query_user_isin
  • req: {“name”:channel name,”account”:account of the user}
  • Returns: isin（1: in the channel; 0:not in the channel）
Retrieves a list of the users in a channel.
  • name: io.agora.signal.channel_query_userlist
  • req: {“name”:channel name}
  • Returns: {“num”:number of the users in the channel,”list”:the latest user}
Retrieves a list of the latest users in a channel.
  • name: io.agora.signal.channel_query_userlist_all
  • req: {“name”:channel name,”num”:number (by default 1000*1000)}
  • Returns: {“num”:number of the users in the channel,”list”:the latest users}
  • Agora recommends using it on the server. If using it on the client, pay attention to the limit on the usage frequency.
Clears all attributes of a specific channel.
  • name: io.agora.signal.channel_clear_attr
  • req: {“channel”:channel name}
Deletes an attribute of a specific channel.
  • name: io.agora.signal.channel_del_attr
  • req: {“channel”:channel name,”name”:attribute name}
Sets an attribute of a specific channel.
  • name: io.agora.signal.channel_set_attr
  • req: {“channel”:channel name,”name”:attribute name,”value”:value name}

Sends a Point-to-point Message (messageInstantSend)

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

messageInstantSend(peer, msg, cb)
Parameter Description
peer Other user’s account.
msg Message. Maximum length is 8 k.
cb Callback function upon successful execution of this method.

Sample code:

session.messageInstantSend = function(peer, msg, cb)

Log out of Agora's Signaling System (logout)

This method logs out of Agora’s signaling system.

logout()

Allows a User to Join a Channel (channelJoin)

This method allows a user to join a channel and returns a channel object.

channelJoin(channelID)
Parameter Description
channelID/

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.

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

Sample code:

var do_join = function(name){
    log('Joining channel' +  name);

    channel = session.channelJoin(name);
};

Initiates a Call (channelInviteUser2)

This method initiates a call; such as, to invite another user to join a specific channel.

channelInviteUser2(channelID, peer, extra) : Call

If the call fails, the user will receive the onInviteFailed callback function. Possible reasons include:

  • The other user is offline.
  • Local network issues.
  • Server errors.
Parameter Description
channelID Channel name.
peer The other user’s account.
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 function will be triggered immediately.
  • {“_require_peer_online”:0} If the counterpart is offline for more than 20 seconds, the onInviteFailed callback function 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.

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

Callback Functions

A User has Logged into the Agora’s Signaling System (onLoginSuccess)

This callback function is triggered when a user has logged into Agora’s signaling system.

onLoginSuccess(uid)
Parameter Description
uid Set as O.

An Error has Occurred During SDK Runtime (onError)

This callback function is triggered when an error is detected.

onError(evt)
Parameter Description
evt Login event.

Sample code:

The Remote Calling Process has Succeeded (cb)

This callback function is triggered when the remote calling process has succeeded.

cb(err, ret);
Parameter Description
callID CallID introduced by invoke()
err Error code
resp Returned JSON value

A User has Failed to Log into Agora’s Signaling System (onLoginFailed)

This callback function is triggered when a user has failed to log into Agora’s signaling system.

onLoginFailed(ecode)
Parameter Description
ecode

The error code.

  • SUCCESS = 0,
  • LOGOUT_E_OTHER = 100
  • LOGOUT_E_USER = 101, // logout by the user
  • LOGOUT_E_NET = 102, // network failure
  • LOGOUT_E_KICKED = 103, // login another device
  • LOGOUT_E_PACKET = 104,
  • LOGOUT_E_TOKENEXPIRED = 105, // token expired
  • LOGOUT_E_OLDVERSION = 106,
  • LOGOUT_E_TOKENWRONG = 107,
  • LOGOUT_E_ALREADY_LOGOUT = 108,
  • LOGIN_E_OTHER = 200,
  • LOGIN_E_NET = 201,
  • LOGIN_E_FAILED = 202,
  • LOGIN_E_CANCEL = 203,
  • LOGIN_E_TOKENEXPIRED = 204,
  • LOGIN_E_OLDVERSION = 205,
  • LOGIN_E_TOKENWRONG = 206,
  • LOGIN_E_TOKEN_KICKED = 207,
  • LOGIN_E_ALREADY_LOGIN = 208,
  • JOINCHANNEL_E_OTHER = 300,
  • SENDMESSAGE_E_OTHER = 400,
  • SENDMESSAGE_E_TIMEOUT = 401,
  • QUERYUSERNUM_E_OTHER = 500,
  • QUERYUSERNUM_E_TIMEOUT = 501,
  • QUERYUSERNUM_E_BYUSER = 502,
  • LEAVECHANNEL_E_OTHER = 600,
  • LEAVECHANNEL_E_KICKED = 601,
  • LEAVECHANNEL_E_BYUSER = 602,
  • LEAVECHANNEL_E_LOGOUT = 603,
  • LEAVECHANNEL_E_DISCONN = 604,
  • INVITE_E_OTHER = 700,
  • INVITE_E_REINVITE = 701,
  • INVITE_E_NET = 702,
  • INVITE_E_PEEROFFLINE = 703,
  • INVITE_E_TIMEOUT = 704,
  • INVITE_E_CANTRECV = 705,
  • GENERAL_E = 1000,
  • GENERAL_E_FAILED = 1001,
  • GENERAL_E_UNKNOWN = 1002,
  • GENERAL_E_NOT_LOGIN = 1003,
  • GENERAL_E_WRONG_PARAM = 1004,
  • GENERAL_E_LARGE_PARAM = 1005

A User has Logged out of Agora’s Signaling System (onLogout)

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

onLogout(reason)
Parameter Description
ecode Error code.

A Message has been Received (onMessageInstantReceive)

This callback function notifies a user that a message has been received.

onMessageInstantReceive(account, uid, msg)
Parameter Description
account Caller’s account.
uid Set as 0.
msg Received instant message.

A Call Request has been Received (onInviteReceived)

This callback function is received by the callee when the callee has received a call invitation or request.

onInviteReceived(call)

Call

Methods

Accepts a Call Invitation (channelInviteAccept)

This method accepts a call invitation. Once this method is called, the caller will receive the onInviteAcceptedByPeer callback function.

channelInviteAccept(extra)
Parameter Description
extra Extra information about the call. Use a string, a JSON string. Can be “”.

Rejects a Call (channelInviteRefuse)

This method to rejects a call invitation. Once this API is called, the other user will receive the onInviteRefusedByPeer event.

channelInviteRefuse(extra)
Parameter Description
extra Extra information about the call. Use a string, a JSON string, or NULL.

Sends a DTMF (Dual-tone Multi-frequency) Message to the Other User (channelInviteDTMF)

This method sends a DTMF message to the other user by calling through the SIP gateway. The receiver will receive the onInviteMsg callback function.

channelInviteDTMF(dtmf)
Parameter Description
dtmf Subsequent analog phone number (DTMF) to be entered after the call goes through.

Ends a Call (channelInviteEnd)

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

channelInviteEnd()

Callback Functions

The Callee has Received the Call Request (onInviteReceivedByPeer)

This callback function is received by the caller when the callee has received the call invitation or request.

onInviteReceivedByPeer(extra)
Parameter Description
extra Extra information about the call. Use a string, a JSON string, or Null.

The Callee has Accepted the Call Request (onInviteAcceptedByPeer)

This callback function is received by the caller when the callee has accepted the call invitation or request.

onInviteAcceptedByPeer(extra)
Parameter Description
extra Extra information about the call. Use a string, a JSON string, or Null.

The Callee has Rejected the Call Request (onInviteRefusedByPeer)

This callback function is received by the caller when the callee rejects the call invitation or request.

onInviteRefusedByPeer(extra)
Parameter Description
extra Extra information about the call. Use a string, a JSON string, or Null.

A Call has Failed (onInviteFailed)

This callback function is triggered when a call has failed.

onInviteFailed(extra)
Parameter Description
extra Extra information about the call. Use a string, a JSON string, or Null.

The Callee has Ended the Call (onInviteEndByPeer)

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

onInviteEndByPeer(extra)
Parameter Description
extra Extra information about the call. Use a string, a JSON string, or Null.

The Caller has Ended the Call (onInviteEndByMyself)

This callback function is triggered when the caller has ended the call.

onInviteEndByMyself(extra)
Parameter Description
extra Extra information about the call. Use a string, a JSON string, or Null.

Sample code:

A Message sent by the Callee has been Received (onInviteMsg)

This callback function is triggered when the caller has received the message sent by the callee.

onInviteMsg(extra)
Parameter Description
extra Extra information about the call. Use a string, a JSON string, or Null.

Channel

Methods

Sends a Channel Message (messageChannelSend)

This method sends a channel message, and all users in the same channel receive the onMessageChannelReceive callback function.

messageChannelSend(msg, cb)
Parameter Description
msg Channel message.
cb Callback function when this method is called successfully.

Sample code:

channel.messageChannelSend( "message", function(){
  // channel message was sent
});

Allows a User to Leave a Channel (channelLeave)

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

channelLeave(cb)
Parameter Description
cb Callback function when this method is called successfully.

Sample code:

channel.channelLeave(function(){
// left the channel
});

Sets 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 function.

channelSetAttr(k, v, cb)
Parameter Description
k Attribute name.
v Attribute value.
cb Callback function when this method is called successfully.

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

Attributes Description
_userNotification
  • 1: (Default) The channel sends the callback function that a user has joined or left the channel.
  • 0: The channel does not send the callback function 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: (Default) Disabled
  • 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.

Sample code:

channel.channelSetAttr("name", "john", function(){
  // attr name was set

});

Deletes a Channel Attribute (channelDelAttr)

This method deletes a specific attribute of the current channel.

channelDelAttr(k, cb)
Parameter Description
k Attribute name.
cb Callback function when this method is called successfully.

Sample code:

channel.channelDelAttr("name", function(){
  // attr name was deleted
});

Deletes all Channel Attributes (channelClearAttr)

This method deletes all attributes of the current channel.

channelClearAttr(cb)
Parameter Description
cb Callback function when this method is called successfully.

Sample code:

channel.channelClearAttr(function(){
  // attr was cleared
});

Callback Functionss

A User has Joined a Channel (onChannelJoined)

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

onChannelJoined()

A User has Failed to Join a Channel (onChannelJoinFailed)

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

onChannelJoinFailed(ecode)
Parameter Description
ecode Error code.

A User has Left a Channel (onChannelLeaved)

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

onChannelLeaved(code)
Parameter Description
ecode Error code.

Another User has Joined the Channel (onChannelUserJoined)

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

onChannelUserJoined(account, uid)
Parameter Description
account User ID defined by the client.
uid Set as 0.

Another User has Left the Channel (onChannelUserLeaved)

This callback function is triggered when another user has left the channel.

onChannelUserLeaved(account, uid)
Parameter Description
account User ID defined by the client.
uid Set as 0.

The User List in the Channel (onChannelUserList)

A user will receive this callback function after joining a channel.

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

onChannelUserList(users)
Parameter Description
users User list of the channel the user has joined, with the following format: [[account1, uid1], [account2, uid2], …, [accountn, uidn]].

The Channel Attribute has Changed (onChannelAttrUpdated)

This callback function is triggered when the channel attribute has changed.

onChannelAttrUpdated(k, v, type)
Parameter Description
k Attribute name.
v Attribute value.
type

The change types:

  • “update”: Update
  • “del”: Delete
  • “clear”: Delete all
  • “set”: N/A

A Channel Message has been Received (onMessageChannelReceive)

This callback function is triggered when a channel message has been received.

onMessageChannelReceive(account, uid, msg)
Parameter Description
account User ID defined by the client.
uid System generated internal uid.
msg Message.

Error Codes and Warning Codes

See Error Codes and Warning Codes.