Skip to main content

Presence

The presence feature enables users to publicly display their online presence status and quickly determine the status of others. Users can also customize their presence status, which adds fun and diversity to real-time chatting.

This page shows how to use the Chat RESTful APIs to implement presence in your project. Before calling the following methods, ensure that you meet the following:

  • You understand the call frequency limit of the Chat RESTful APIs as described in Limitations.
  • You have activated the presence feature in Agora Console.

Common parameters

ParameterTypeDescriptionRequired
hostStringThe domain name assigned by the Chat service to access RESTful APIs. For how to get the domain name, see Get the information of your project.Yes
org_nameStringThe unique identifier assigned to each company (organization) by the Chat service. For how to get the org name, see Get the information of your project.Yes
app_nameStringThe unique identifier assigned to each app by the Chat service. For how to get the app name, see Get the information of your project.Yes
uidStringThe unique login account of the user.

Authorization

Chat RESTful APIs require Bearer HTTP authentication. Every time an HTTP request is sent, the following Authorization field must be filled in the request header:


_1
Authorization: Bearer ${YourAppToken}

In order to improve the security of the project, Agora uses a token (dynamic key) to authenticate users before they log in to the chat system. Chat RESTful APIs only support authenticating users using app tokens. For details, see Authentication using App Token.

Set the presence status of a user

Sets the presence status of a user.

For each App Key, the call frequency limit of this method is 50 per second.

HTTP request


_1
POST https://{host}/{org_name}/{app_name}/users/{uid}/presence/{resource}/{status}

Path parameter

ParameterTypeDescriptionRequired
resourceStringThe unique identifier assigned to each device resource in the format {Device Type}_{Resource ID}, where the device type can be android, ios, or web, followed by a resource ID assigned by the SDK.Yes
statusStringThe presence status defined by the user:
  • 0: Offline.
  • 1: Online
  • Other strings: Custom status.
  • Yes

    For the descriptions of the other path parameters, see Common Parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringThe content type. Set it to application/json.Yes
    AuthorizationStringThe authentication token of the user or administrator, in the format of Bearer ${token}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    Request body

    ParameterTypeDescriptionRequired
    extStringThe extension information of the presence status. The size of the extension field can be a maximum of 64 bytes.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the data field in the response body contains the following parameters:

    ParameterTypeDescription
    resultStringWhether the setting of the presence status succeeds. ok indicates the presence setting succeeds; otherwise, you can troubleshoot according to the returned reasons.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible causes.

    Example

    Request example


    _4
    curl -X POST 'a1-test.agora.com:8089/5101220107132865/test/users/c1/presence/android_123423453246/0' \
    _4
    -H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
    _4
    -H 'Content-Type: application/json' \
    _4
    -d '{"ext":"123"}'

    Response example


    _1
    {"result":"ok"}%

    Subscribe to the presence status of multiple users

    Subscribes to the presence status of multiple users.

    For each App Key, the call frequency limit of this method is 50 per second.

    HTTP request


    _1
    POST https://{host}/{org_name}/{app_name}/users/{uid}/presence/{expiry}

    Path parameter

    ParameterTypeDescriptionRequired
    expiryStringThe subscription duration in seconds. The maximum value is 2,592,000, which equals 30 days.Yes

    For the descriptions of the other path parameters, see Common Parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringThe content type. Set it to application/json.Yes
    AuthorizationStringThe authentication token of the user or administrator, in the format of Bearer ${token}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    Request body

    ParameterTypeDescriptionRequired
    usernamesJSON ArrayThe list of users to whom you subscribe, for example, [“user1”, “user2”]. This list can contain a maximum of 100 usernames.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the data field in the response body contains the following parameters:

    ParameterTypeDescription
    resultJSON ArrayWhether the subscription succeeds. If successful, the presence statuses of the users return; otherwise, you can troubleshoot according to the returned reasons.
    uidStringThe unique login account of the user.
    last_timeNumberThe Unix timestamp when the user was last online.
    expiryNumberThe Unix timestamp when the subscription expires.
    extStringThe extension information of the presence status.
    statusJSON ArrayThe presence statuses on multiple devices of the user.
  • 0: Offline.
  • 1: Online.
  • Other strings: The custom presence status defined by the user.
  • If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible causes.

    Example

    Request example


    _4
    curl -X POST 'a1-test.agora.com:8089/5101220107132865/test/users/wzy/presence/1000' \
    _4
    -H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
    _4
    -H 'Content-Type: application/json' \
    _4
    -d '{"usernames":["c2","c3"]}'

    Response example


    _1
    {"result":[{"uid":"","last_time":"1644466063","expiry":"1645500371","ext":"123","status":{"android":"1","android_6b5610ac-4e11-4661-82b3-dee17bc7b2cc":"0"}},{"uid":"c3","last_time":"1645183991","expiry":"1645500371","ext":"","status":{"android":"0","android_6b5610ac-4e11-4661-82b3-dee17bc7b2cc":"0"}}]}%

    Retrieve the presence status of multiple users

    Retrieves the presence status of multiple users.

    For each App Key, the call frequency limit of this method is 50 per second.

    HTTP request


    _1
    POST https://{host}/{org_name}/{app_name}/users/{uid}/presence

    Path parameter

    For the descriptions of the path parameters, see Common Parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringThe content type. Set it to application/json.Yes
    AuthorizationStringThe authentication token of the user or administrator, in the format of Bearer ${token}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    Request body

    ParameterTypeDescriptionRequired
    usernamesJSON ArrayThe list of users whose presence statuses you attempt to retrieve, for example, [“user1”, “user2”]. This list can contain a maximum of 100 usernames.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the data field in the response body contains the following parameters:

    ParameterTypeDescription
    resultStringWhether the setting of the presence status succeeds. ok indicates the presence setting succeeds; otherwise, troubleshoot according to the returned reasons.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible causes.

    ParameterTypeDescription
    resultJSON ArrayWhether the retrieving operation succeeds. If successful, the presence statuses of the users return; otherwise, you can troubleshoot according to the returned reasons.
    uidStringThe unique login account of the user.
    last_timeNumberThe Unix timestamp when the user was last online.
    extStringThe extension information of the presence status.
    statusJSON ArrayThe presence statuses on multiple devices of the user.
  • 0: Offline.
  • 1: Online.
  • Other strings: The custom presence status defined by the user.
  • Example

    Request example


    _4
    curl -X POST 'a1-test.agora.com:8089/5101220107132865/test/users/wzy/presence' \
    _4
    -H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
    _4
    -H 'Content-Type: application/json' \
    _4
    -d '{"usernames":["c2","c3"]}'

    Response example


    _15
    {
    _15
    "result":[
    _15
    {"uid":"c2",
    _15
    "last_time":"1644466063",
    _15
    "ext":"",
    _15
    "status":{"android":"0"}
    _15
    },
    _15
    {"uid":"c3",
    _15
    "last_time":"1644475330",
    _15
    "ext":"",
    _15
    "status":{
    _15
    "android":"0",
    _15
    "android":"0"}
    _15
    }]
    _15
    }

    Unsubscribe from the presence status of multiple users

    Unsubscribes from the presence status of multiple users.

    For each App Key, the call frequency limit of this method is 50 per second.

    HTTP request


    _1
    DELETE https://{host}/{org_name}/{app_name}/users/{uid}/presence

    Path parameter

    For the descriptions of the path parameters, see Common Parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringThe content type. Set it to application/json.Yes
    AuthorizationStringThe authentication token of the user or administrator, in the format of Bearer ${token}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    Request body

    ParameterTypeDescriptionRequired
    usersJSON ArrayThe list of users from whom you unsubscribe, for example, [“user1”, “user2”]. This list can contain a maximum of 100 usernames.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the data field in the response body contains the following parameters:

    ParameterTypeDescription
    resultStringWhether the subscription cancellation succeeds. ok indicates the subscription cancellation succeeds; otherwise, you can troubleshoot according to the returned reasons.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible causes.

    Example

    Request example


    _4
    curl -X DELETE 'a1-test.agora.com:8089/5101220107132865/test/users/wzy/presence' \
    _4
    -H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
    _4
    -H 'Content-Type: application/json' \
    _4
    -d '["c1"]'

    Response example


    _1
    {"result":"ok"}%

    Retrieve the subscriptions of a user

    Retrieves the subscriptions of a user in a paginated list.

    For each App Key, the call frequency limit of this method is 50 per second.

    HTTP request


    _1
    GET https://{host}/{org_name}/{app_name}/users/{uid}/presence/sublist?pageNum=1&pageSize=100

    Path parameter

    ParameterTypeDescriptionRequired
    pageNumIntThe page from which to start retrieving subscriptions. Pass in 1 at the first query.Yes
    pageSizeIntThe maximum number of subscriptions to retrieve per page. The range is [1, 500].Yes

    For the descriptions of the other path parameters, see Common Parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringThe content type. Set it to application/json.Yes
    AuthorizationStringThe authentication token of the user or administrator, in the format of Bearer ${token}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the data field in the response body contains the following parameters:

    ParameterTypeDescription
    resultStringWhether the retrieving operation succeeds. If successful, the subscription information returns; otherwise, you can troubleshoot according to the returned reasons.
    totalnumStringThe total number of the users you subscribe to.
    sublistObjectThe list of subscriptions. Each object in the list contains the uid and expiry fields.
    uidStringThe unique login account of the user.
    expiryStringThe Unix timestamp when the subscription expires.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible causes.

    Example

    Request example


    _3
    curl -X GET 'a1-test.agora.com:8089/5101220107132865/test/users/wzy/presence/sublist?pageNum=1&pageSize=100' \
    _3
    -H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
    _3
    -H 'Content-Type: application/json'

    Response example


    _1
    {"result":{"totalnum":"2","sublist":[{"uid":"lxml2","expiry":"1645822322"},{"uid":"lxml1","expiry":"1645822322"}]}}%

    Status codes

    For details, see HTTP Status Codes.

    Page Content