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 API 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.

​

Parameter	Type	Description	Required
host	String	The 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_name	String	The 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_name	String	The 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
uid	String	The unique login account of the user.

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.

Sets the presence status of a user.

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

_1

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

Parameter	Type	Description	Required
resource	String	The 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
status	String	The 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.

Parameter	Type	Description	Required
Content-Type	String	The content type. Set it to application/json.	Yes
Authorization	String	The 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

Parameter	Type	Description	Required
ext	String	The extension information of the presence status. The size of the extension field can be a maximum of 64 bytes.	Yes

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

Parameter	Type	Description
result	String	Whether 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.

_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"}'

_1

{"result":"ok"}%

Subscribes to the presence status of multiple users.

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

_1

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

Parameter	Type	Description	Required
expiry	String	The 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.

Parameter	Type	Description	Required
Content-Type	String	The content type. Set it to application/json.	Yes
Authorization	String	The 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

Parameter	Type	Description	Required
usernames	JSON Array	The list of users to whom you subscribe, for example, [“user1”, “user2”]. This list can contain a maximum of 100 usernames.	Yes

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

Parameter	Type	Description
result	JSON Array	Whether the subscription succeeds. If successful, the presence statuses of the users return; otherwise, you can troubleshoot according to the returned reasons.
uid	String	The unique login account of the user.
last_time	Number	The Unix timestamp when the user was last online.
expiry	Number	The Unix timestamp when the subscription expires.
ext	String	The extension information of the presence status.
status	JSON Array	The 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.

_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"]}'

_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"}}]}%

Retrieves the presence status of multiple users.

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

_1

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

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

Parameter	Type	Description	Required
Content-Type	String	The content type. Set it to application/json.	Yes
Authorization	String	The 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

Parameter	Type	Description	Required
usernames	JSON Array	The list of users whose presence statuses you attempt to retrieve, for example, [“user1”, “user2”]. This list can contain a maximum of 100 usernames.	Yes

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

Parameter	Type	Description
result	String	Whether 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.

Parameter	Type	Description
result	JSON Array	Whether the retrieving operation succeeds. If successful, the presence statuses of the users return; otherwise, you can troubleshoot according to the returned reasons.
uid	String	The unique login account of the user.
last_time	Number	The Unix timestamp when the user was last online.
ext	String	The extension information of the presence status.
status	JSON Array	The presence statuses on multiple devices of the user. 0: Offline. 1: Online. Other strings: The custom presence status defined by the user.

_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"]}'

_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

}

Unsubscribes from the presence status of multiple users.

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

_1

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

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

Parameter	Type	Description	Required
Content-Type	String	The content type. Set it to application/json.	Yes
Authorization	String	The 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

Parameter	Type	Description	Required
users	JSON Array	The list of users from whom you unsubscribe, for example, [“user1”, “user2”]. This list can contain a maximum of 100 usernames.	Yes

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

Parameter	Type	Description
result	String	Whether 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.

_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"]'

_1

{"result":"ok"}%

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.

_1

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

Parameter	Type	Description	Required
pageNum	Int	The page from which to start retrieving subscriptions. Pass in 1 at the first query.	Yes
pageSize	Int	The 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.

Parameter	Type	Description	Required
Content-Type	String	The content type. Set it to application/json.	Yes
Authorization	String	The 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

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

Parameter	Type	Description
result	String	Whether the retrieving operation succeeds. If successful, the subscription information returns; otherwise, you can troubleshoot according to the returned reasons.
totalnum	String	The total number of the users you subscribe to.
sublist	Object	The list of subscriptions. Each object in the list contains the uid and expiry fields.
uid	String	The unique login account of the user.
expiry	String	The 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.

_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'

_1

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

For details, see HTTP Status Codes.