Skip to main content

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

Android
iOS
macOS
Web
Linux C++
Unity

User and channel events

Authentication

The Signaling RESTful API only supports HTTPS. To authenticate your request, refer to the RESTful API authentication guidelines.

API overview

Using Signaling RESTful API, you can get information regarding:

Data format

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

  • Request: Refer to the examples in the following APIs.
  • Response: The response content is in JSON format.
  • Base URL: https://api.agora.io/dev/v2/project/<appid>
    where <appid> is the Agora app ID for your project.
info

All the request URLs and request bodies are case-sensitive.

Get user events

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

info
  • The number of requests for each app ID must not exceed 10 per second.
  • 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 events are stored by geographical regions.
  • If you pull events from one geographical region, you may get the same events when you pull from a different geographical region. This is because Agora only synchronizes events within a geographical region and not 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.
eventsJSONAn array of login and logout events.

An event contains the following content:


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

ParameterTypeDescription
user_idStringThe corresponding user ID.
typeStringEvent type:
  • Login: The user logged in to Signaling.
  • Logout: The user logged out of Signaling.
  • msintNumber of seconds since January 1, 1970 (UTC) to the UTC time when the server receives the message.

    Get channel events

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

    info
    • The number of requests for each app ID must not exceed 10 per second.
    • 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 events are stored by geographical region.
    • 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 synchronizes events within a geographical region and not 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.
    eventsJSONAn array of join and leave event.

    An 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 corresponding channel ID.
    user_idStringThe corresponding user ID.
    typeStringThe event type:
  • Join: A user has joined the channel.
  • Leave: A user has left the channel.
  • msintNumber of seconds since January 1, 1970 (UTC) to the UTC time when the server receives the message.

    Status codes

    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.

    Ensure service reliability

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

    Switch the domain name

    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.

    Precautions

    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.

    Domain name table

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

    Primary domain nameRegion domain nameRegion
    api.sd-rtn.comapi-us-west-1.sd-rtn.comWestern United States
    api-us-east-1.sd-rtn.comEastern United States
    api-ap-southeast-1.sd-rtn.comSoutheast Asia Pacific
    api-ap-northeast-1.sd-rtn.comNortheast Asia Pacific
    api-eu-west-1.sd-rtn.comWestern Europe
    api-eu-central-1.sd-rtn.comCentral Europe
    api-cn-east-1.sd-rtn.comEast China
    api-cn-north-1.sd-rtn.comNorth China
    api.agora.ioapi-us-west-1.agora.ioWestern United States
    api-us-east-1.agora.ioEastern United States
    api-ap-southeast-1.agora.ioSoutheast Asia Pacific
    api-ap-northeast-1.agora.ioNortheast Asia Pacific
    api-eu-west-1.agora.ioWestern Europe
    api-eu-central-1.agora.ioCentral Europe
    api-cn-east-1.agora.ioEast China
    api-cn-north-1.agora.ioNorth China

    Signaling