User and channel events REST API

For the user events and channel events RESTful API, the number of requests per second for each App ID must not exceed 10.

Authentication​

The Signaling RESTful API only supports HTTPS. You can use either of the following methods to authenticate your HTTP request:

• Basic authentication
• Token authentication

Basic authentication​

For basic HTTP authentication, you need to put api_key:api_secret in the Authorization field of the HTTP header. For more information on how to generate the Authorization filed, see RESTful API authentication.

Token authentication​

For token authentication, you need to put the following information to the x-agora-token field and the x-agora-uid field when sending your HTTP request:

• The Signaling Token generated at your server.
• The uid you use to generate the Signaling Token.

For more information on how to generate the x-agora-token field and the x-agora-uid field, see RESTful API authentication.

• Get user events: Call the Gets user events API.
• Get channel events: Call the Gets channel events API.

All requests are sent to the host api.agora.io. See Ensure service reliability for alternate domain names.

• Request: See the examples in the following APIs.
• Response: The response content is in JSON format.
• Base URL: https://api.agora.io/dev/v2/project/<appid>

Note: <appid> is the App ID used by your project. All the request URLs and request bodies are case-sensitive.

Gets user events (GET)​

This method gets the user events from the address specified by the Agora Signaling server. Events you acquired from this API are removed from the Agora Signaling server. You cannot get the same event twice.

• The number of requests per second for each App ID must not exceed 10.
• The Signaling backend stores a maximum of 2,000 events. If the number of events exceeds 2,000, the latest event replaces the oldest event.
• The backend returns a maximum of 1,000 events each time.
• Agora does not guarantee the time sequence of events across geographical regions (countries or continents), because Agora stores events by geographical regions.
• If you have pulled events from one geographical region, you may get the same events when you pull from a different geographical region. This is because Agora only synchronize events within a geographical region and does not synchronize events across geographical regions.

• Method: GET
• Endpoint: /rtm/vendor/user_events
• Request URL：

_1

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/vendor/user_events

_5

{

_5

"result": "success",

_5

"request_id" : "10116762670167749259",

_5

"events" : [event]

_5

}

Parameter	Type	Description
result	string	The result of this request.
request_id	string	The unique ID of this request.
events	JSON	A login or logout event.

[event] contains the following content:

_5

{

_5

"user_id": "rtmtest_RTM_4852_4857w7%",

_5

"type" : "Login",

_5

"ms" : 1578027420761

_5

}

Parameter	Type	Description
user_id	string	The user ID involved.
type	string	Event type: Login: A user has logged in the Agora Signaling system. Logout: A user has logged out of the Agora Signaling system.
ms	int	Number of seconds starting from January 1, 1970 (UTC) to the UTC time when the server receives the message.

Gets channel events (GET)​

This method gets the channel events from the address specified by the Agora Signaling server. Events you acquired from this API are removed from the Agora Signaling server. You cannot get the same event twice.

• The number of requests per second for each App ID must not exceed 10.
• The Signaling server stores a maximum of 2,000 events. If the number of events exceeds 2,000, the latest event replaces the oldest event.
• The backend returns a maximum of 1,000 events each time.
• Agora does not guarantee the time sequence of events across geographical regions (countries or continents), because Agora stores events by geographical regions.
• If you have pulled events from one geographical region, you may get the same events when you pull from a different geographical region. This is because Agora only synchronize events within a geographical region and does not synchronize events across geographical regions.

• Method: GET
• Endpoint: /rtm/vendor/channel_events
• Request URL:

_1

https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/vendor/channel_events

_5

{

_5

"result": "success",

_5

"request_id" : "10116762670167749259",

_5

"events" : [event]

_5

}

Parameter	Type	Description
result	string	The result of this request.
request_id	string	The unique ID of this request.
events	JSON	A join or leave event.

[event] contains the following content:

_6

{

_6

"group_id": "example_channel_id",

_6

"user_id": "rtmtest_RTM_4852_4857w7%",

_6

"type" : "Join",

_6

"ms" : 1578027418981

_6

}

Parameter	Type	Description
group_id	string	The channel ID involved.
user_id	string	The user ID involved.
type	string	The event type: Join: A user has joined the channel. Leave: A user has left the channel.
ms	int	Number of seconds starting from January 1, 1970 (UTC) to the UTC time when the server receives the message.

The following table contains the most common HTTP status codes for Signaling.

Status code	Description
200	The request succeeds.
400	Incorrect request syntax.
408	The server request times out or the server fails to respond.
429	Too many requests.

This section presents the overall strategy you use to ensure high availability of REST services.

To ensure high availability of REST services, Agora enables you to switch domain names when you experience service outage due to regional network failures. Take the following steps to set up and switch your domain name:

1. Set the primary domain name based on the location of your service server:

   • If the DNS address of the service server is located in a country or region other than mainland China, set the primary domain name to api.agora.io.
   • If the DNS address of the service server is in mainland China, set the primary domain name to api.sd-rtn.com.

2. If your attempt to initiate a RESTful API request using the primary domain fails, set up your retry strategy as follows:

   1. Primary domain retry: Retry using the same primary domain name.

   2. Alternate domain retry:

      • If the current primary domain name is api.sd-rtn.com, use api.agora.io as the alternate domain name.
      • If the current primary domain name is api.agora.io, use api.sd-rtn.com as the alternate domain name.

   3. Adjacent domain retry: If alternate domain retry fails, retry using the domain name adjacent to the current region.

      For example, suppose your business server is located in Europe. You set the primary domain name to api.agora.io, and the business server resolves the primary domain name to Germany. Germany is located in central Europe (api-eu-central-1.agora.io). The domain name table shows that the adjacent area is West Europe. Use the api-eu-west-1.agora.io or api-eu-west-1.sd-rtn.com domain name to retry.

Take the following precautions when setting up your retry strategy:

• To avoid exceeding the QPS limit with retry requests, best practice is to use a back-off strategy. For example, wait 1 second before you retry for the first time, wait 3 seconds before retrying the second time, and wait 6 seconds before retry a third time.

• If the request fails because of a network problem rather than a DNS domain name resolution problem, skip alternate domain retry and proceed to adjacent domain retry.

• Before switching to the region domain name, ensure that the REST services you wish to use, for example, cloud recording or channel management, are deployed in that region.

The following table shows the primary and region domain names for various regions.

Primary domain name	Region domain name	Region
api.sd-rtn.com	api-us-west-1.sd-rtn.com	Western United States
	api-us-east-1.sd-rtn.com	Eastern United States
	api-ap-southeast-1.sd-rtn.com	Southeast Asia Pacific
	api-ap-northeast-1.sd-rtn.com	Northeast Asia Pacific
	api-eu-west-1.sd-rtn.com	Western Europe
	api-eu-central-1.sd-rtn.com	Central Europe
	api-cn-east-1.sd-rtn.com	East China
	api-cn-north-1.sd-rtn.com	North China
api.agora.io	api-us-west-1.agora.io	Western United States
	api-us-east-1.agora.io	Eastern United States
	api-ap-southeast-1.agora.io	Southeast Asia Pacific
	api-ap-northeast-1.agora.io	Northeast Asia Pacific
	api-eu-west-1.agora.io	Western Europe
	api-eu-central-1.agora.io	Central Europe
	api-cn-east-1.agora.io	East China
	api-cn-north-1.agora.io	North China