离线推送设置 REST API

更新时间：2022-07-27

本文展示如何调用环信即时通讯 RESTful API 实现离线推送，包括设置离线推送通知显示的昵称、推送通知方式及免打扰模式。调用以下方法前，请先参考限制条件了解即时通讯 RESTful API 的调用频率限制。

以下表格列举了即时通讯 RESTful API 的公共请求参数和响应参数：

环信即时通讯 REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，必须在请求 header 部填入如下 Authorization 字段：

Authorization: Bearer ${YourAppToken}

为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 REST API 仅支持使用 App Token 的鉴权方式，详见使用 Token 鉴权。

设置离线推送时显示的昵称。

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

参数及说明详见 公共参数。

请求包体为 JSON Object 类型，包含以下字段：

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

其他参数及说明详见 公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考错误码了解可能的原因。

curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourToken>' -d '{    "nickname": "testuser"   }' 'http://XXXX/XXXX/XXXX/users/user1'

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

设置离线推送通知在客户端的展示方式，设置即时生效。服务端据此向用户推送离线消息。

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

参数及说明详见 公共参数。

请求包体为 JSON Object 类型，包含以下字段：

其他参数及说明详见 公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考错误码了解可能的原因。

curl -X PUT -H "Authorization: Bearer <YourToken>" -i  https://XXXX/XXXX/XXXX/users/a -d '{"notification_display_style": "1"}'

{
  "action" : "put",
  "application" : "17d59e50-XXXX-XXXX-XXXX-0dc80c0f5e99",
  "path" : "/users",
  "uri" : "https://XXXX/XXXX/XXXX/users",
  "entities" : [
    {
      "uuid" : "3b8c9890-XXXX-XXXX-XXXX-f50bf55cafad",
      "type" : "user",
      "created" : 1530276298905,
      "modified" : 1534407146060,
      "username" : "user1",
      "activated" : true,
      "notification_no_disturbing" : false,
      "notification_no_disturbing_start" : 1,
      "notification_no_disturbing_end" : 3,
      "notification_display_style" : 1,
      "nickname" : "testuser",
      "notifier_name" : "2882303761517426801"
      } ],
"timestamp" : 1534407146058,
"duration" : 3,
"organization" : "1112171214115068",
"applicationName" : "testapp"
}

设置离线推送免打扰模式，在免打扰期间，用户将不会收到离线消息推送。

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

参数及说明详见 公共参数。

请求包体为 JSON Object 类型，包含以下字段：

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

其他参数及说明详见 公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考错误码了解可能的原因。

设置免打扰时间段

curl -X PUT -H "Authorization: Bearer <YourToken>" -i  "https://XXXX/XXXX/XXXX/users/a " -d '{"notification_no_disturbing": true,"notification_no_disturbing_start": "1","notification_no_disturbing_end": "3"}'

关闭免打扰模式

curl -X PUT -H "Authorization: Bearer <YourToken>" -i  "https://XXXX/XXXX/XXXX/users/a " -d '{"notification_no_disturbing": false}'

{
  "action" : "put",
  "application" : "17d59e50-XXXX-XXXX-XXXX-0dc80c0f5e99",
  "path" : "/users",
  "uri" : "https://XXXX/XXXX/XXXX/users",
  "entities" : [
    {
    "uuid" : "3b8c9890-XXXX-XXXX-XXXX-f50bf55cafad",
    "type" : "user",
    "created" : 1530276298905,
    "modified" : 1534405429835,
    "username" : "User1",
    "activated" : true,
    "notification_no_disturbing" : true,
    "notification_no_disturbing_start" : 1,
    "notification_no_disturbing_end" : 3,
    "notification_display_style" : 0,
    "nickname" : "testuser",
    "notifier_name" : "2882303761517426801"
    } ],
"timestamp" : 1534405429833,
"duration" : 4,
"organization" : "1112171214115068",
"applicationName" : "testapp"
}

你可以设置全局离线推送的通知方式和免打扰模式以及单个单聊或群聊会话的离线推送设置。

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

其他参数及说明详见 公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考错误码了解可能的原因。

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

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

查询指定单聊、指定群聊或全局的离线推送设置。

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

其他参数及说明详见 公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考错误码了解可能的原因。

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

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

设置离线推送消息的翻译语言。

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

参数及说明详见 公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

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

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

查询离线推送消息的翻译语言。

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

参数及说明详见 公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考错误码了解可能的原因。

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

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

创建离线推送消息模板。

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

参数及说明详见 公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考错误码了解可能的原因。

curl -X POST '{url}/{org}/{app}/notification/template' \
-H 'Authorization: Bearer <YourToken>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "name": "test7",
    "title_pattern": "你好,{0}",
    "content_pattern": "推送测试,{0}"
}'

{
    "uri": "https://XXXX/XXXX/XXXX/notification/template",
    "timestamp": 1646989584108,
    "organization": "hx",
    "application": "17fe201b-XXXX-XXXX-XXXX-1ed1ebd7b227",
    "action": "post",
    "data": {
        "name": "test7",
        "createAt": 1646989584124,
        "updateAt": 1646989584124,
        "title_pattern": "你好,{0}",
        "content_pattern": "推送测试,{0}"
    },
    "duration": 26,
    "applicationName": "hxdemo"
}

查询离线推送消息使用的模板。

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

其他参数及说明详见 公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考错误码了解可能的原因。

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

{
    "uri": "https://XXXX/XXXX/XXXX/notification/template/test7",
    "timestamp": 1646989686393,
    "organization": "hx",
    "application": "17fe201b-XXXX-XXXX-XXXX-1ed1ebd7b227",
    "action": "get",
    "data": {
        "name": "test7",
        "createAt": 1646989584124,
        "updateAt": 1646989584124,
        "title_pattern": "你好,{0}",
        "content_pattern": "推送测试,{0}"
    },
    "duration": 11,
    "applicationName": "hxdemo"
}

删除离线消息推送模板。

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

其他参数及说明详见 公共参数。

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。

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

{
    "uri": "https://XXXX/XXXX/XXXX/notification/template",
    "timestamp": 1646989686393,
    "organization": "hx",
    "application": "17fe201b-XXXX-XXXX-XXXX-1ed1ebd7b227",
    "action": "delete",
    "data": {
        "name": "test7",
        "createAt": 1646989584124,
        "updateAt": 1646989584124,
        "title_pattern": "你好,{0}",
        "content_pattern": "推送测试,{0}"
    },
    "duration": 11,
    "applicationName": "hxdemo"
}