Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

You are looking at Signaling v1.x Docs. The newest version is  Signaling 2.x

Android
iOS
Web
macOS
Windows
Linux C++
Linux Java
Unity

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

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.

API sequence

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>

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.

Request example

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

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

Response example


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

ParameterTypeDescription
resultstringThe result of this request.
request_idstringThe unique ID of this request.
eventsJSONA login or logout event.

[event] contains the following content:


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

ParameterTypeDescription
user_idstringThe user ID involved.
typestringEvent type:
  • Login: A user has logged in the Agora Signaling system.
  • Logout: A user has logged out of the Agora Signaling system.
  • msintNumber 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.

    Request example

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

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

    Response example


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

    ParameterTypeDescription
    resultstringThe result of this request.
    request_idstringThe unique ID of this request.
    eventsJSONA 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
    }

    ParameterTypeDescription
    group_idstringThe channel ID involved.
    user_idstringThe user ID involved.
    typestringThe event type:
  • Join: A user has joined the channel.
  • Leave: A user has left the channel.
  • msintNumber of seconds starting from January 1, 1970 (UTC) to the UTC time when the server receives the message.

    Status code

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

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

    Signaling