User and Channel Events RESTful API

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.

API sequence

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

Data format

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>

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.

Request example

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

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

Response example

{
    "result": "success",
    "request_id" : "10116762670167749259",
    "events" : [event]
}

[event] contains the following content:

{
    "user_id": "rtmtest_RTM_4852_4857w7%",
    "type" : "Login",
    "ms" : 1578027420761
}

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.

Request example

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

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

Response example

{
    "result": "success",
    "request_id" : "10116762670167749259",
    "events" : [event]
}

[event] contains the following content:

{
    "group_id": "example_channel_id",
    "user_id": "rtmtest_RTM_4852_4857w7%",
    "type" : "Join",
    "ms" : 1578027418981
}

Status code

The following table contains the most common HTTP status codes for Real-time Messaging.