Signaling API - Android Beta

Methods

Account Information System

Login(login)

public void login(String appId,String account,String token,int uid,String deviceID);

This method allows the users to log into the Agora signaling system. The users must log in before they can perform any action.

It triggers the onLoginSuccess callback upon a successful execution, otherwise it returns onLoginFailed. If the application lost the connection with the server, it returns the onLogout callback.

Parameter Description
appId App ID provided by Agora at https://dashboard.agora.io.
account

User ID defined by the client. It can be up to 128 visible characters (space is not permitted currently).

It can be the uid, nickname, guid and other content as long as it is unique.

The account parameter mentioned across this document follow the same rule.

token Signaling Key generated by App ID and App Certificate. See Agora Keys User Guide for details.
uid Expired, set it as 0.
deviceID Set it as NULL.

Login(login2)

It triggers the onLoginSuccess callback upon a successful execution.

public void login2(String appId,String account,String token,int uid,String deviceID, int retry_time_in_s, int retry_count);

This method allows the users to log into the Agora signaling system.

Parameter Description
appId App ID provided by Agora at https://dashboard.agora.io.
account

User ID defined by the client. It can be up to 128 visible characters (space is not permitted currently).

It can be the uid, nickname, guid and other content as long as it is unique.

The account parameter mentioned across this document follow the same rule.

token Signaling Key generated by App ID and App Certificate. See Agora Keys User Guide for details.
uid Expired, set it as 0.
deviceID Set it as NULL.
retry_time_in_s The length of the time it retries to login, 30 seconds by default.
retry_count The number it retries to login, 3 times by default.

Log out(logout)

It triggers the onLogout callback upon a successful execution.

public void logout();

Check Login Status(isOnline)

public int isOnline();

This method checks whether the user is logged in the Agora signaling system or not, online or offline.

Parameter Description
Return Value

1: Online

0: Offline

Send Point-to-Point Message(messageInstantSend)

public void messageInstantSend(String account,int uid,String msg,String msgID);

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

Upon a successful execution, the user receives onMessageSendSuccess event, and the other user receives onMessageInstantReceive.

If the execution fails, the user receives onMessageSendError event.

Parameter Description
account User ID defined by the client.
uid

Obsolete.

Set it as 0.

msg

Message body.

Each message must be no greater than 8K visible characters.

Set User Attributes(set_attr)

public void set_attr(String name,String value);

This method sets the user attributes.

Parameter Description
name

Attribute name.

It can be up to 256 visible characters

value

Attribute value.

It can be up to 128 visible characters

Get Your Own User Attributes(get_attr)

This method gets your own user attributes. You will receive the onUserAttrResult event.

public void get_attr(String name);
Parameter Description
name

Attribute name.

It can be up to 256 visible characters

Get All of Your Own Attributes(get_attr_all)

public void get_attr_all();

This method gets all of your attributes. You will receive the onUserAttrResult upon a successful execution.

Get Attributes of Specific User(get_user_attr)

public void get_user_attr(String account,String name);

This method allows the user to get the attributes of a specific user. The user will receive onUserAttrResult event.

Parameter Description
account User ID defined by the client.
name

Attribute name.

It can be up to 256 visible characters

Get All attributes of Specific User(get_user_attr_all)

public void get_user_attr_all(String account);

This method allows the user to get all the attributes of a specific user. The user will receive the onUserAttrAllResult callback upon a successful execution.

Parameter Description
account User ID defined by the client.

Channel System

Join Channel(channelJoin)

public void channelJoin(String channelID);

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.

Once the user joins a channel, he/she receives the onChannelJoined callback, and other users in the same channel receive the onChannelUserJoined callback. If the user fails to join a specified channel, he/she receives the onChannelJoinFailed callback.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters.

Leave Channel(channelleave)

public void channelLeave(String channelID);

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

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters.

Query Channel User Number(channelQueryUserNum)

public void channelQueryUserNum(String channelID);

This method allows the users to query the number of users in a specified channel. Upon a successful execution, the users will receive the onChannelQueryUserNumResult callback.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters.

Set Channel Attributes(channelSetAttr)

public void channelSetAttr(String channelID,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 event.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters.

name

Attribute name.

It can be up to 128 visible characters .

value

Attribute value.

It can be up to 1024 visible characters .

Delete Channel Attributes(channelDelAttr)

public void channelDelAttr(String channelID,String name);
Parameter Description
channelID

Channel name.

It can be up to 128 visible characters.

name

Attribute name.

It can be up to 128 visible characters.

Delete All Channel Attributes(channelClearAttr)

public void channelClearAttr(String channelID);

This method deletes all the attributes of a specified channel.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters.

Send Channel Message(messageChannelSend)

public void messageChannelSend(String channelID,String msg,String msgID);

This method sends channel message, and all users in the same channel receive onMessageChannelReceive event.

The user who sent the message receives onMessageSendSuccess event upon a successful execution, otherwise, receives onMessageSendError.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

msg

Message body.

In a large group call, each message must be no greater than 1K visible characters.

Each user cannot send more than 60 message per second, the entire channel can not send more than 600 messages per second.

In an one-on-one call, each message must be no greater than 8K visible characters.

msgID

Visible characters, can be set as NULL.

It is used to mark the callback message.

Call System

Initiate a Call(channelInviteUser)

public void channelInviteUser(String channelID,String account,int uid);

This method initiates a call, that is, inviting other user to join a specific channel. If the call fails, the user will receive onInviteFailed event. Possible reasons are listed as follows:

  • The other user is offline;
  • Network issue in the local;
  • Server error;

If the user(calling) gets confirmation from the other user(called), the user will receive onInviteReceivedByPeer event, and the other will receive onInviteReceived.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

account User ID of the other user defined by the client.
uid Obsolete. Set it as 0.

Initiate a Call (channelInviteUser2)

public void channelInviteUser2(String channelID,String account,String extra);

Same as above with different parameters.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

account User ID of the other user defined by the client.
extra

Additional Information the caller wants to deliver to the callee.

For example, this is video call or audio call.

It must be JSON format.

Send DTMF Message to Other User(channelInviteDTMF)

public void channelInviteDTMF(String channelID,String phoneNum,String dtmf);

This method sends DTMF message to the other user for calling via SIP gateway.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

phoneNum The phone number of the other user.
dtmf The subsequent analog phone number(DTMF) to be entered after the call gets through.

Accept Call(channelInviteAccept)

public void channelInviteAccept(String channelID,String account,int uid);

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

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

account User ID of the other user defined by the client.
uid

Obsolete.

Set it as 0.

Reject Call(channelInviteRefuse)

public void channelInviteRefuse(String channelID,String account,int uid);

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

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters .

account User ID of the other user defined by the client.
uid

Obsolete.

Set it as 0.

End Call(channelInviteEnd)

public void channelInviteEnd(String channelID,String account,int uid);

This method closed the call after the call has been connected. The user receives the onInviteEndByMyself event, and the other user receives onInviteEndByPeer.

Parameter Description
channelID

Channel name.

It can be up to 128 visible characters.

account User ID of the other user defined by the client.
uid

Obsolete.

Set it as 0.

Internal-test or Obsolete Interface

Interface Prototype Description
messageAppSend public void messageAppSend(String msg,String msgID); Agora internal test only
messageChannelSendFast public void messageChannelSendFast(String channelID,String msg,String msgID); Agora internal test only
messagePushSend public void messagePushSend(String account,int uid,String msg,String msgID); Agora internal test only
messageChatSend public void messageChatSend(String account,int uid,String msg,String msgID); Agora internal test only
messageDTMFSend public void messageDTMFSend(int uid,String msg,String msgID); Obsolete
setBackground public void setBackground(int bOut); Agora internal test only
setNetworkStatus public void setNetworkStatus(int bOut); Agora internal test only
Ping public void ping(); Agora internal test only
channelInvitePhone public void channelInvitePhone(String channelID,String phoneNum,int uid); Obsolete
channelInvitePhone2 public void channelInvitePhone2(String channelID,String phoneNum,String sourcesNum); Obsolete
channelInvitePhone3 public void channelInvitePhone3(String channelID,String phoneNum,String sourcesNum,String extra); Obsolete

Events

Connection Lost Event(onReconnecting)

public void onReconnecting(int nretry);

This event is triggered when the connection with the Agora signaling system is lost after login.

Parameter Description
nretry The current reconnection number.

Connection Recovered Event(onReconnected)

public void onReconnected(int fd);

This event is triggered when the application is reconnected to the Agora signaling system. When the reconnection fails, the event onLogout will be triggered instead.

Parameter Description
fd For Agora internal use.

User Online Event(onLoginSuccess)

public void onLoginSuccess(int uid,int fd);

This event is triggered when the user is logged into the Agora signaling system.

Parameter Description
fd For Agora internal use.

User Offline Event(onLogout)

public void onLogout(int ecode);

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

Parameter Description
ecode error code

User Login Failed Event(onLoginFailed)

public void onLoginFailed(int ecode);

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

Parameter Description
ecode error code

User Joined Channel Event(onChannelJoined)

public void onChannelJoined(String channelID);

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

Parameter Description
channelID Channel name

User Failed to Join Channel Event(onChannelJoinFailed)

public void onChannelJoinFailed(String channelID,int ecode);

This event is triggered when the user fails to join a channel.

Parameter Description
channelID Channel name
ecode error code

User Left Channel Event(onChannelLeaved)

public void onChannelLeaved(String channelID,int ecode);

This event is triggered when the user left a channel.

Parameter Description
channelID Channel name
ecode error code

Other User Joined Channel Event(onChannelUserJoined)

public void onChannelUserJoined(String account,int uid);

This event is triggered when other user joined the channel.

Parameter Description
account User ID defined by the client.
uid obsolete

Other User Left Channel Event(onChannelUserLeaved)

public void onChannelUserLeaved(String account,int uid);

This event is triggered when other user left the channel.

Parameter Description
account User ID defined by the client.
uid obsolete

User List Received Event(onChannelUserList)

public void onChannelUserList(String[] accounts, int[] uids);

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

Parameter Description
accounts List of User IDs defined by the client.
uids obsolete

User Number Received Event(onChannelQueryUserNumResult)

public void onChannelQueryUserNumResult(String channelID,int ecode,int num);

This event is triggered when the user has queried the user number of the channel.

Parameter Description
channelID Channel name
ecode Error code
num The query result

Channel Attribute Changed Event(onChannelAttrUpdated)

public void onChannelAttrUpdated(String channelID,String name,String value,String type);

This event is triggered when the channel attribute is changed.

Parameter Description
channelID Channel name
name Attribute name
value Attribute value
type

Change types:

  • “update”: Update
  • “del”: Delete
  • “clear”: Delete all

Call Invitation Received Event(onInviteReceived)

public void onInviteReceived(String channelID,String account,int uid,String extra);

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

Parameter Description
channelID Channel name
account User ID of the other user defined by the client.
uid obsolete
extra

Additional Information the caller wants to deliver to the callee.

For example, this is video call or audio call.

It must be JSON format.

Other User Received Call Event(onInviteReceivedByPeer)

public void onInviteReceivedByPeer(String channelID,String account,int uid);

This event is received the caller when the other user has received the call invitation/request.

Parameter Description
channelID Channel name
account User ID of the other user defined by the client.
uid obsolete

Other User Accepted Call Event(onInviteAcceptedByPeer)

public void onInviteAcceptedByPeer(String channelID,String account,int uid, String extra);

This event is received by the caller when the other user has accepted the call invitation/request.

Parameter Description
channelID Channel name
account User ID of the other user defined by the client.
uid obsolete
extra

Additional Information the caller wants to deliver to the callee.

For example, this is video call or audio call.

It must be JSON format.

Other User Rejected Call Event(onInviteRefusedByPeer)

public void onInviteRefusedByPeer(String channelID,String account,int uid);

This event is received by the caller when the other user rejected the call invitation/request.

Parameter Description
channelID Channel name
account User ID of the other user defined by the client.
uid obsolete

Call Failed Event (onInviteFailed)

public void onInviteFailed(String channelID,String account,int uid,int ecode);

This event is triggered when a call fails.

Parameter Description
channelID Channel name
account User ID of the other user defined by the client.
uid obsolete

Other User Ended Call Event(onInviteEndByPeer)

public void onInviteEndByPeer(String channelID,String account,int uid, String extra);

This event is triggered when the other user ended the call.

Parameter Description
channelID Channel name
account User ID of the other user defined by the client.
msg Message body
extra

Additional Information the caller wants to deliver to the callee.

For example, this is video call or audio call.

It must be JSON format.

Call Ended Event(onInviteEndByMyself)

public void onInviteEndByMyself(String channelID,String account,int uid);

This event is received by the user when the user ended the call.

Parameter Description
channelID Channel name
account User ID of the other user defined by the client
uid obsolete
msg Message body

Message Received Event(onInviteMsg)

public void onInviteMsg(String channelID, String account, int uid, String msgType, String msgData, String extra)

This event is triggered when you have received the DTMF message sent from the other user.

Parameter Description
channelID Channel name. It can be up to 128 visible characters
account User ID of the other user defined by the client
uid Obsolete.
msgType The message Type. Currently it means DTMF
msgData The detailed DTMF message. The supported string scope: 0-9, * , #
extra The extra information of the call, which can be a string, a JSON string, or NULL.

Message Failed Event(onMessageSendError)

public void onMessageSendError(String messageID,int ecode);

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

Parameter Description
messageID Message ID
ecode Error code

Message Sent Event(onMessageSendSuccess)

public void onMessageSendSuccess(String messageID);

This event is triggered when the user sent a message successfully.

Parameter Description
messageID Message ID

Other User Received Message Event(onMessageInstantReceive)

public void onMessageInstantReceive(String account,int uid,String msg);

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

Parameter Description
account User ID defined by the client
uid Obsolete
msg Message body

Channel Message Received Event(onMessageChannelReceive)

public void onMessageChannelReceive(String channelID,String account,int uid,String msg);

This event is trigged upon receiving the channel message.

Parameter Description
channelID Channel name
account User ID defined by the client
uid obsolete
msg Message body

Log Printed Event(onLog)

public void onLog(String txt);

This event is trigged upon a line of log is printed out.

Parameter Description
txt Content of a log line

Attribute Received Event(onUserAttrResult)

public void onUserAttrResult(String account,String name,String value);

This event is triggered when the user has queried the attribute of a specific user.

Parameter Description
account User ID defined by the client
name Attribute name
value The json value of all attributes

All Attribute Received Event(onUserAttrAllResult)

public void onUserAttrAllResult(String account,String value);

This event is triggered when the user has queried all the attributes of a specific user.

Parameter Description
account User ID defined by the client
value The json value of all attributes

Internal-test or Obsolete Interface

Interface Prototype Description
onMessageAppReceived public void onMessageAppReceived(String msg); Agora internal test only