Server SDK API Beta

Server SDK API 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.
LoginCallback Class An internal class of the Signaling Class that manages login-related callbacks.
MessageCallback Class An internal class of the Signaling Class that manages message-related callbacks.
ChannelCallback Class An internal class of the Signaling Class that manages channel-related callbacks.
CallCallback Class An internal class of the Signaling Class that manages call-related 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.

Note

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)

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

Enable a 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 login Agora’s signaling system and it returns a LoginSession instance object. You must login before performing any action.

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 Signaling Key generated from the App ID and App Certificate. See Get a 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

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)

public void logout();

This method triggers the onLogout callback upon a successful execution.

Send a Point-to-point Message (messageInstantSend)

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

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

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)

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

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

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)

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

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

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

Join a Channel (channelJoin)

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

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.

Parameter Description
channelID

Channel name. It can be up to 128 visible characters, and includes the following two special channels:

  • _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.

Note

The special channels are to be used by the servers only to receive login and channel events.

Channel Class

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

Methods

Leave a Channel (channelLeave)

public void 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.

Set the Channel Attributes (channelSetAttr)

public void channelSetAttr(String name, String value)

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

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 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 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)

Delete a Channel Attribute (channelDelAttr)

public void channelDelAttr(String name)

This method deletes a specific attribute of the current channel.

Parameter Description
name Attribute name. Maximum length is 128 visible characters.

Delete all Channel Attributes (channelClearAttr)

public void channelClearAttr()

This method deletes all attributes of the current channel.

Send a Channel Message (messageChannelSend)

public void messageChannelSend(String msg)

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

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)

public void channelInviteAccept()

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

Accept a Call (channelInviteAccept)

public void channelInviteAccept(String extra)

This method accepts the received call request/invitation.

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.

Reject a 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 a 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 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)

public void channelInviteEnd(String extra)

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

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)

public void channelInviteEnd()

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

LoginCallback Class

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

Callbacks

User Online Callback (onLoginSuccess)

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

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

Parameter Description
session Session name.
uid Internal User ID generated by the system.

User Offline Callback (onLogout)

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

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

Parameter Description
session Session name.
ecode Error code.

User Login Failed Callback (onLoginFailed)

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

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

Parameter Description
session Session name.
ecode Error code.

Message Received Callback (onMessageInstantReceive)

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

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

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)

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

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

Parameter Description
session Session name.
call 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 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)

public void onMessageSendSuccess(Signal.LoginSession session)

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

Parameter Description
session Session name.

Message Failure Callback (onMessageSendError)

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

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

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)

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

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

Parameter Description
session Session name.
channel 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 a user has failed to join a channel.

Parameter Description
session Session name.
channel Channel name.
ecode 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 Session name.
channel Channel name.
ecode 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 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)

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

This callback is triggered when a user has joined a channel with less than 200 people.

Parameter Description
session Session name.
channel Channel name.
users List of user accounts used to login the app.
uid Internal user ID generated 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 a channel attribute is changed.

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)

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 Session name.
channel Channel name.
account Account of the other user defined by the client.
msg Message body.

CallCallback Class

An internal class of the Signaling Class that 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 a call invitation/request.

Parameter Description
session Session name.
call Call object.

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 a call invitation/request.

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)

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

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

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)

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

This callback is triggered when a call fails.

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)

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 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)

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

This callback is triggered when the user ended the call.

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)

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 Session name.
call Call object.
extra Extra information the caller wants to deliver to the callee. Must be in JSON format.
Is this page helpful?