Offline Push

This page shows how to call Chat RESTful APIs to set the display name, display style, push notification mode, and do-not-disturb (DND) mode.

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 advanced features for push in Agora Console. Advanced features allow you to set the push notification mode, do-not-disturb mode, and custom push template.

Common parameters

The following table lists common request and response parameters of the Chat RESTful APIs:

Request parameters

Response parameters

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:

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. The Chat RESTful API only supports authenticating users using app tokens. For details, see Authentication using App Token.

Set the display name in push notifications

Sets the nickname displayed in push notifications.

For each App Key, the total call frequency limit of this method and the method to set the display style is 100 per second.

HTTP request

PUT https://{host}/{org_name}/{app_name}/users/{username}

Path parameter

For the descriptions of path parameters, see Common Parameters.

Request header

Request body

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -d '{    "nickname": "testuser"   }' 'http://a1.agora.com/agora-demo/testapp/users/user1'

Response example

{  
  "action": "put",  
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",  
  "path": "/users",  
  "uri": "https://a1.agora.com/agora-demo/testapp/users",  
  "entities": [    
    {      
      "uuid": "4759aa70-eba5-11e8-925f-6fa0510823ba",      
      "type": "user",      
      "created": 1542595573399,      
      "modified": 1542596083687,      
      "username": "user1",      
      "activated": true,      
      "nickname": "testuser"    
      }  ],  
"timestamp": 1542596083685,  
"duration": 6,  
"organization": "agora-demo",  
"applicationName": "testapp"
}

Set the display style in push notifications

Sets the display style of push notifications.

For each App Key, the total call frequency limit of this method and the method to set the display name is 100 per second.

HTTP request

PUT https://{host}/{org_name}/{app_name}/users/{username}

Path parameter

For the descriptions of path parameters, see Common Parameters.

Request header

Request body

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

curl -X PUT -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EKeAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFDSEF2E" -i  https://a1.agora.com/agora-demo/testapp/users/a -d '{"notification_display_style": "1"}'

Response example

{  
  "action" : "put",  
  "application" : "17d59e50-0aee-11e8-8092-0dc80c0f5e99",  
  "path" : "/users",  
  "uri" : "https://a1.agora.com/agora-demo/testapp/users",  
  "entities" : [ 
    {    
      "uuid" : "3b8c9890-7b9a-11e8-9d88-f50bf55cafad",    
      "type" : "user",    
      "created" : 1530276298905,    
      "modified" : 1534407146060,   
      "username" : "user1",    
      "activated" : true,      
      "notification_display_style" : 1,    
      "nickname" : "testuser",    
      "notifier_name" : "2882303761517426801"  
      } ],  
"timestamp" : 1534407146058,  
"duration" : 3,  
"organization" : "1112171214115068",  
"applicationName" : "testapp"
}

Set up push notifications

Sets the push notification and DND modes at both the app and conversation levels.

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

HTTP request

PUT https://{host}/{org}/{app}/users/{username}/notification/{type}/{key}

Path parameter

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

Request header

Request body

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

curl -L -X PUT '{url}/{org_name}/{app_name}/users/{username}/notification/user/{key}' \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/json' \
--data-raw '{
    "type":"NONE",
    "ignoreInterval":"21:30-08:00",
    "ignoreDuration":86400000
}'

Response example

{
    "path": "/users",
    "uri": "https://localhost/hx/hxdemo/users/notification/user/hxtest",
    "timestamp": 1647503749918,
    "organization": "hx",
    "application": "17fe201b-ad9b-4a3a-83df-1ed1ebd7b227",
    "action": "put",
    "data": {
        "type": "NONE",
        "ignoreDuration": 1647590149924,
        "ignoreInterval": "21:30-08:00"
    },
    "duration": 20,
    "applicationName": "hxdemo"
}

Retrieve the settings of push notifications

Retrieves the push notification and DND modes at both the app and conversation levels.

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

HTTP request

GET https://{host}/{org}/{app}/users/{username}/notification/{type}/{key}

Path parameter

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

Request header

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

curl -L -X GET '{url}/{org}/{app}/users/{username}/notification/chatgroup/{key}' \
-H 'Authorization: Bearer {token}' 

Response example

{
    "path": "/users",
    "uri": "https://localhost/hx/hxdemo/users/notification/chatgroup/12312312321",
    "timestamp": 1647503749918,
    "organization": "hx",
    "application": "17fe201b-ad9b-4a3a-83df-1ed1ebd7b227",
    "action": "get",
    "data": {
        "type": "NONE",
        "ignoreDuration": 1647590149924,
        "ignoreInterval": "21:30-08:00"
    },
    "duration": 20,
    "applicationName": "hxdemo"
}

Set the preferred language of push notifications

Sets the preferred language of push notifications.

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

HTTP request

PUT https://{host}/{org}/{app}/users/{username}/notification/language

Path parameter

For the descriptions of path parameters, see Common Parameters.

Request header

Request body

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

curl -L -X PUT '{url}/{org}/{app}/users/{username}/notification/language' \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/json' \
--data-raw '{
    "translationLanguage":"EU"
}'

Response example

{
    "path": "/users",
    "uri": "https://localhost/hx/hxdemo/users/notification/language",
    "timestamp": 1648089630244,
    "organization": "hx",
    "application": "17fe201b-ad9b-4a3a-83df-1ed1ebd7b227",
    "action": "put",
    "data": {
        "language": "EU"
    },
    "duration": 66,
    "applicationName": "hxdemo"
}

Retrieve the preferred language of push notifications

Retrieves the preferred language of push notifications.

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

HTTP request

GET https://{host}/{org}/{app}/users/{username}/notification/language

Path parameter

For the descriptions of path parameters, see Common Parameters.

Request header

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

curl -L -X GET '{url}/{org}/{app}/users/{username}/notification/language' \
-H 'Authorization: Bearer {token}'

Response example

{
    "path": "/users",
    "uri": "https://localhost/hx/hxdemo/users/notification/language",
    "timestamp": 1648089630244,
    "organization": "hx",
    "application": "17fe201b-ad9b-4a3a-83df-1ed1ebd7b227",
    "action": "put",
    "data": {
        "language": "EU"
    },
    "duration": 66,
    "applicationName": "hxdemo"
}

Create a push template

Creates a template for push notifications.

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

HTTP request

POST https://{host}/{org}/{app}/notification/template`

Path parameter

For the descriptions of path parameters, see Common Parameters.

Request header

Request body

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

curl -X POST '{url}/{org}/{app}/notification/template' \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/json' \
--data-raw '{
    "name": "test7",
    "title_pattern": "Hello,{0}",
    "content_pattern": "Test,{0}"
}'

Response example

{
    "uri": "https://localhost/hx/hxdemo/notification/template",
    "timestamp": 1646989584108,
    "organization": "hx",
    "application": "17fe201b-ad9b-4a3a-83df-1ed1ebd7b227",
    "action": "post",
    "data": {
        "name": "test7",
        "createAt": 1646989584124,
        "updateAt": 1646989584124,
        "title_pattern": "Hello,{0}",
        "content_pattern": "Test,{0}"
    },
    "duration": 26,
    "applicationName": "hxdemo"
}

Retrieve a push template

Retrieves the specified template for push notifications.

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

HTTP request

GET https://{host}/{org}/{app}/notification/template/{name}

Path parameter

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

Request header

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

curl -X GET '{url}/{org}/{app}/notification/template/{name}' \
-H 'Authorization: Bearer {token}'  

Response example

{
    "uri": "https://localhost/hx/hxdemo/notification/template/test7",
    "timestamp": 1646989686393,
    "organization": "hx",
    "application": "17fe201b-ad9b-4a3a-83df-1ed1ebd7b227",
    "action": "get",
    "data": {
        "name": "test7",
        "createAt": 1646989584124,
        "updateAt": 1646989584124,
        "title_pattern": "Hello,{0}",
        "content_pattern": "Test,{0}"
    },
    "duration": 11,
    "applicationName": "hxdemo"
}

Delete a push template

Deletes the specified template for push notifications.

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

HTTP request

DELETE https://{host}/{org}/{app}/notification/template/{name}

Path parameter

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

Request header

HTTP response

Response body

If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

For other fields and detailed descriptions, see Common parameters.

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

Example

Request example

curl -X DELETE '{url}/{org}/{app}/notification/template' \
-H 'Authorization: Bearer {token}' 

Response example

{
    "uri": "https://localhost/hx/hxdemo/notification/template",
    "timestamp": 1646989686393,
    "organization": "hx",
    "application": "17fe201b-ad9b-4a3a-83df-1ed1ebd7b227",
    "action": "delete",
    "data": {
        "name": "test7",
        "createAt": 1646989584124,
        "updateAt": 1646989584124,
        "title_pattern": "Hello,{0}",
        "content_pattern": "Test,{0}"
    },
    "duration": 11,
    "applicationName": "hxdemo"
}

Status codes

For details, see HTTP Status Codes.