Signaling Function Overview Beta

Introduction

This document only describes the main function by accessing the Agora Signaling System. For details on how to implement the functions on each platform, refer to:

The users can access the Agora Signaling System in one of the following ways:

  • SDK access
  • Server API access
  • SIP Gateway access
../../_images/access.png

By accessing the Agora Signaling System using either of the above methods, the users can implement the following main functions:

Note

The users can also use a Non-Agora Signaling System to dock with other Agora CaaS services.

Account Information System

This section introduces the account information system in details and things that the users must pay attention to.

The account information system is the basis of channel system and call system. The users can reliably send and receive messages, and carry out other business after login.

The account of the Agora signaling system is the unique identity for each user, which does not require users to register.

Message Queue

Each user has his/her own message queue:

  • Message will not be lost regardless of whether the user is online or not.
  • Message may be timed out, and the time limits for different messages are not the same.

Login

Users can send or receive messages or perform other actions only after logging into the Agora signaling system.

After login, a network outage might occur temporarily. During this period, users can neither receive any message nor perform any action. When the network recovers, the user can then receive messages. The messages will not be lost if it is not timed-out.

The SDK triggers the onLogout event if the network has been interrupted for too long, and the server also marks the user as “Logout”. If so, the users must call login again before they can continue the operations.

One account can only log onto one device instead of multiple devices simultaneously. Whenever you log in, you will kicked out from the last login device (SDK triggers the onLogout event) automatically.

Attributes

Each user has his/her own attribute table:

Users can set some attributes, which they or other users can read. The attributes usually store contents like the address of the user profile picture, nickname and etc.

Event and Query

  • The users can query the status and attributes of other users.
  • The users can subscribe the status and attribute changes of other users(only applicable to Server API).

Plant-text Messages

The users can send plain text messages to each other, for example, text, web site, image address, json and etc.

Channel System

The channel system supports a large number of users simultaneously online, and provides reliable channel events, properties and messages. Typical scenarios include audio and video conferencing messages, microphone control, video broadcast channel news etc.

The signaling channel, based on a reliable account information system, ensures zero package loss, on which the users can build the service system in a reliable way.

When the network is temporarily interrupted, the users are unable to receive any message. Once the network recovers, the users receive all the messages during the interruption. If the network has been blocked, the SDK triggers onLogout event and the server background sets the user as “Logout”, and automatically kicks the users out of the channel.

Note

The signaling channel and the media channel (using Agora Native SDK) are independent:

  • The signaling channel controls the conference (send reliable message, receive reliable callback events, and support adding attributes and etc).
  • The media channel is used for audio and video communication (transmitting sound and image).

Joining a Channel

  • The users must log into the Agora signaling system before joining any channel.
  • The users can only join one channel, and whenever the users join a channel, they will be automatically kicked out from the channel they have joined previously.
  • The users leave a channel automatically upon logout.
  • The users get a complete user list in the channel automatically once they have joined in the channel.

Note

The users will not receive the user list automatically in a large channel (for example, with over 200 people).

Channel Events

The users can receive all the channel events (other user joined, left, and etc) once joining a channel. All channel events are reliable without package loss.

Channel Messages

The channel messages are broadcasting messages, which means all users in the same channel will receive them.

Channel Attributes

Each channel has an attribute table, and all users can get this table once joining a channel. Each user can modify the attributes and all users in the same channel will receive notification whenever a change is made on the attributes.

Call System

The call system provides audio and video calls and external SIP calls, including hybrid call session with VOIP users and PSTN phone users.

The users can use video or audio communication without the call system if all sides join the same channel.

Call system is used to initiate a call, invite other users to join a channel in one-on-one video or audio communication or conference call:

  • The users must stay as “Login” to receive a call;
  • The users can call Agora internal users. Internal user refers to the users registered to the Agora signaling system.
  • The users can call the external users via SIP gateway. They can use SIP gateway to call external users at PSTN, call centers, PBX, IM and etc.
  • Each call only reaches one person, and a group communication can initiate multiple calls. Each call is independent, and the users can call Agora internal users, or call external users via SIP gateway.
  • The users can initiate a call using Server API, and it is a more reliable way to initiate a call using Server API for a multi-party communication by assigning the call status to other users through channel attributes and channel messages.

Call Timed-out

Once you have initiated a call, and if you have not received the confirmation from the other user within 30 seconds, the call fails as timed-out.

Upon receipt of the confirmation, you, as the caller, decides by yourself when to end the call if the other user does not accept or reject the call within a certain period.

Call Flow

The call system provides audio and video calls and external SIP calls, including hybrid call session with VOIP users and PSTN phone users.

Call and channel are independent, which means the users can use one of the following methods to call:

Method Advantage Disadvantage
Call first, then join channel after the call gets through Bill will occur only when the call officially starts(users can talk to each other directly). It takes longer before the call can official start.
The called subscribers cannot view the fuzzy video before they answer the call
Join channel first, then call Users can start he call officially faster; Even if the called subscriber does not answer the call, bill will still occur for a single channel
The called subscribers can view the fuzzy video before they answer the call

The following is the call flow of joining a channel first before initialing a call:

../../_images/call-flow.png