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 Real-time Messaging 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 RTM Token generated at your server.
• The uid you use to generate the RTM 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.

• 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 RTM server. Events you acquired from this API are removed from the Agora RTM server. You cannot get the same event twice.

• The number of requests per second for each App ID must not exceed 10.
• The RTM 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 RTM system. Logout: A user has logged out of the Agora RTM 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 RTM server. Events you acquired from this API are removed from the Agora RTM server. You cannot get the same event twice.

• The number of requests per second for each App ID must not exceed 10.
• The RTM 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 Real-time Messaging.

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.