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, thelogin
call will be ignored. To cancel the previous login, calllogout
first without having to wait until it is successfully executed. The system will stop reconnecting to the server, if eitherreconnect_count
orreconnect_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.
|
level |
Sets the level of the system log.
|
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. |
|
Sets a user attribute. |
|
Retrieves a user attribute. |
|
Retrieves all attributes of a user. |
|
Retrieves the number of the users in a channel. |
|
Checks if a user is in a specific channel. |
|
Retrieves a list of the users in a channel. |
|
Retrieves a list of the latest users in a channel. |
|
Clears all attributes of a specific channel. |
|
Deletes an attribute of a specific channel. |
|
Sets an attribute of a specific channel. |
|
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:
|
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:
|
You do not need to set the
_require_peer_online
field when making a SIP call.
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. |
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.
|
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. Each channel message must not exceed 8 KB visible characters. Each user cannot send more than 60 messages per second, and the entire channel cannot send more than 200 messages per second. |
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 |
|
_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.
|
_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.
|
_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:
|
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. |