Skip to main content

You are viewing Agora Docs forBeta products and features. Switch to Docs

Presence

The presence feature enables users to publicly display their online presence status and quickly determine the status of others. Users can customize their presence status; using more specific terms such as "busy", "away", or "in a call" can add 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 user's presence status on a specific device.

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
uidStringThe user ID of user whose presence status is to be set.Required
resourceStringThe ID of the user's device for which the presence status is set. This device ID is the unique identifier assigned to each device resource in the format {Device Platform}_{Resource ID}, where the device platform can be android, ios, or webim, followed by an underscore plus a resource ID assigned by the SDK. For example, android_34f0bbf7-8eab-46db-b572-b56b02405690.Yes
statusStringThe presence status defined by the user:
  • 0: Offline.
  • 1: Online
  • Other numeric 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 'http://XXXX/XXXX/XXXX/users/c1/presence/android_123423453246/0' \
_4
-H 'Authorization: Bearer <YourAppToken>' \
_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
resultJSONWhether 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, in seconds.
expiryNumberThe Unix timestamp when the subscription expires, in seconds.
extStringThe extension information of the presence status.
statusJSONThe presence statuses on multiple devices of the user.
  • 0: Offline.
  • 1: Online.
  • Other strings: User-defined custom presence status.

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 'http://XXXX/XXXX/XXXX/users/wzy/presence/1000' \
_4
-H 'Authorization: Bearer <YourAppToken>' \
_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
resultJSONWhether 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, in seconds.
extStringThe extension information of the presence status.
statusJSONThe presence statuses on multiple devices of the user.
  • 0: Offline.
  • 1: Online.
  • Other strings: User-defined custom presence status.

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 'http://XXXX/XXXX/XXXX/users/wzy/presence' \
_4
-H 'Authorization: Bearer <YourAppToken>' \
_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 'http://XXXX/XXXX/XXXX/users/wzy/presence' \
_4
-H 'Authorization: Bearer <YourAppToken>' \
_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

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

Query 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

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, in seconds

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 'http://XXXX/XXXX/XXXX/users/wzy/presence/sublist?pageNum=1&pageSize=100' \
_3
-H 'Authorization: Bearer <YourAppToken>' \
_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.

vundefined