Signaling API - Mac Beta

Methods

Account Information System

Login(login)

(void) login:(NSString*)appId account:(NSString*)account token:(NSString*)token uid:(uint32_t)uid deviceID:(NSString*)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)

(void) login2:(NSString*)appId account:(NSString*)account token:(NSString*)token uid:(uint32_t)uid deviceID:(NSString*)deviceID retry_time_in_s:(int)retry_time_in_s retry_count:(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.

(void) logout;

Send Channel Message(messageChannelSend)

(void) messageChannelSend:(NSString*)channelID msg:(NSString*)msg msgID:(NSString*)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.

Set User Attributes(set_attr)

(void) set_attr:(NSString*)name value:(NSString*)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.

(void) get_attr:(NSString*)name;
Parameter Description
name

Attribute name.

It can be up to 256 visible characters

Get All of Your Own Attributes(get_attr_all)

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

(void) get_user_attr:(NSString*)account name:(NSString*)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)

(void) get_user_attr_all:(NSString*)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.

Check Login Status(isOnline)

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

Channel System

Join Channel(channelJoin)

(void) channelJoin:(NSString*)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)

(void) channelLeave:(NSString*)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)

(void) channelQueryUserNum:(NSString*)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)

(void) channelSetAttr:(NSString*)channelID name:(NSString*)name value:(NSString*)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)

(void) channelDelAttr:(NSString*)channelID name:(NSString*)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 .

value

Attribute value.

It can be up to 128 visible characters .

Delete All Channel Attributes(channelClearAttr)

(void) channelClearAttr:(NSString*)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 Point-to-Point Message(messageInstantSend)

(void) messageInstantSend:(NSString*)account uid:(uint32_t)uid msg:(NSString*)msg msgID:(NSString*)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.

Call System

Initiate a Call(channelInviteUser)

(void) channelInviteUser:(NSString*)channelID account:(NSString*)account uid:(uint32_t)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)

- (void) channelInviteUser2:(NSString*)channelID account:(NSString*)account extra:(NSString*)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)

(void) channelInviteDTMF:(NSString*)channelID phoneNum:(NSString*)phoneNum dtmf:(NSString*)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)

(void) channelInviteAccept:(NSString*)channelID account:(NSString*)account uid:(uint32_t)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)

- (void) channelInviteRefuse:(NSString*)channelID account:(NSString*)account uid:(uint32_t)uid extra:(NSString*)extra

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)

(void) channelInviteEnd:(NSString*)channelID account:(NSString*)account uid:(uint32_t)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 (void) messageAppSend:(NSString*)msg msgID:(NSString*)msgID ; Agora internal test only
messageChannelSendFast messageChannelSendFast:(NSString*)channelID msg:(NSString*)msg msgID:(NSString*)msgID ; Agora internal test only
messagePushSend (void) messagePushSend:(NSString*)account uid:(uint32_t)uid msg:(NSString*)msg msgID:(NSString*)msgID ; Agora internal test only
messageChatSend (void) messageChatSend:(NSString*)account uid:(uint32_t)uid msg:(NSString*)msg msgID:(NSString*)msgID ; Agora internal test only
messageDTMFSend (void) messageDTMFSend:(uint32_t)uid msg:(NSString*)msg msgID:(NSString*)msgID ; Obsolete
setBackground (void) setBackground:(uint32_t)bOut ; Agora internal test only
setNetworkStatus (void) setNetworkStatus:(uint32_t)bOut ; Agora internal test only
Ping (void) ping; Agora internal test only
channelInvitePhone (void) channelInvitePhone:(NSString*)channelID phoneNum:(NSString*)phoneNum uid:(uint32_t)uid ; Obsolete
channelInvitePhone2 (void) channelInvitePhone2:(NSString*)channelID phoneNum:(NSString*)phoneNum sourcesNum:(NSString*)sourcesNum ; Obsolete
channelInvitePhone3 (void) channelInvitePhone3:(NSString*)channelID phoneNum:(NSString*)phoneNum sourcesNum:(NSString*)sourcesNum extra:(NSString*)extra ; Obsolete

Events

Connection Lost Event(onReconnecting)

@property (copy) void(^onReconnecting)(uint32_t 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)

@property (copy) 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)

@property (copy) void(^onLoginSuccess)(uint32_t 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)

@property (copy) void(^onLogout)(AgoraEcode ecode) ;

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

Parameter Description
ecode error code

User Login Failed Event(onLoginFailed)

@property (copy) void(^onLoginFailed)(AgoraEcode 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)

@property (copy) void(^onChannelJoined)(NSString* channelID) ;

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

Parameter Description
channelID Channel name

User Failed to Join Channel Event(onChannelJoinFailed)

@property (copy) void(^onChannelJoinFailed)(NSString* channelID,AgoraEcode 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)

@property (copy) void(^onChannelLeaved)(NSString* channelID,AgoraEcode 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)

@property (copy) void(^onChannelUserJoined)(NSString* account,uint32_t 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)

@property (copy) void(^onChannelUserLeaved)(NSString* account,uint32_t 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)

@property (copy) void(^onChannelUserList)(NSMutableArray* accounts, NSMutableArray* 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)

@property (copy) void(^onChannelQueryUserNumResult)(NSString* channelID,AgoraEcode 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)

@property (copy) void(^onChannelAttrUpdated)(NSString* channelID,NSString* name,NSString* value,NSString* 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)

@property (copy) void(^onInviteReceived)(NSString* channelID,NSString* account,uint32_t uid,NSString* extra) ;

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

Parameter Description
channelID Channel name
account User ID 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)

@property (copy) void(^onInviteReceivedByPeer)(NSString* channelID,NSString* account,uint32_t 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 defined by the client.
uid obsolete

Other User Accepted Call Event(onInviteAcceptedByPeer)

@property (copy) void(^onInviteAcceptedByPeer)(NSString* channelID,NSString* account,uint32_t uid,NSString* 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)

@property (copy) void(^onInviteRefusedByPeer)(NSString* channelID,NSString* account,uint32_t uid,NSString* extra) ;

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
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 Failed Event (onInviteFailed)

@property (copy) void(^onInviteFailed)(NSString* channelID,NSString* account,uint32_t uid,AgoraEcode ecode,NSString* extra) ;

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
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 Ended Call Event(onInviteEndByPeer)

@property (copy) void(^onInviteEndByPeer)(NSString* channelID,NSString* account,uint32_t uid,NSString* 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)

@property (copy) void(^onInviteEndByMyself)(NSString* channelID,NSString* account,uint32_t 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)

@property (copy) void(^onInviteMsg)(NSString* channelID,NSString* account,uint32_t uid,NSString* msgType,NSString* msgData,NSString* 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)

@property (copy) void(^onMessageSendError)(NSString* messageID,AgoraEcode 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)

@property (copy) void(^onMessageSendSuccess)(NSString* messageID) ;

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

Parameter Description
messageID Message ID

Other User Received Message Event(onMessageInstantReceive)

@property (copy) void(^onMessageInstantReceive)(NSString* account,uint32_t uid,NSString* msg) ;

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

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

Channel Message Received Event(onMessageChannelReceive)

@property (copy) void(^onMessageChannelReceive)(NSString* channelID,NSString* account,uint32_t uid,NSString* 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)

@property (copy) void(^onLog)(NSString* 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)

@property (copy) void(^onUserAttrResult)(NSString* account,NSString* name,NSString* 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)

@property (copy) void(^onUserAttrAllResult)(NSString* account, NSString* 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 @property (copy) void(^onMessageAppReceived)(NSString* msg) ; Agora internal test only