推送设置 REST API

更新时间:2022-02-28

本文展示如何调用即时通讯 RESTful API 设置消息推送显示昵称、提醒方式及免打扰模式。 调用以下方法前,请先参考限制条件了解即时通讯 RESTful API 的调用频率限制。

包含以下接口:

名称 方法 请求 描述
设置推送消息显示昵称 PUT /{org_name}/{app_name}/users/{username} 设置用户推送消息显示的昵称。
设置推送消息展示方式 PUT /{org_name}/{app_name}/users/{username} 设置用户推送消息展示为仅通知还是详情可见。
设置免打扰 PUT /{org_name}/{app_name}/users/{username} 设置用户是否开启免打扰模式,以及开启/关闭免打扰的时间。

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

Authorization:Bearer ${YourAppToken}

为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 REST API 推荐使用 app token 的 鉴权方式,详见 使用 Token 鉴权

设置推送昵称

设置用户的推送昵称,在离线推送时使用。

基本信息

方法:PUT

接入点:https://{host}/{org_name}/{app_name}/users/{username}

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。
username String 必须 用户的用户名。

请求头

参数 类型 是否必需 描述
Content-Type String 必需 内容类型:application/json
Authorization String 必需 Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

请求体

参数 类型 是否必需 说明
nickname String 非必需 将要改成的推送昵称信息。

响应体

参数 说明
uuid 用户的 UUID,即系统为用户生成唯一标识字段,开发者可以不用关注。
type “user” 用户类型。
username 用户名,也就是环信用户 ID。
nickname 昵称(可选),仅用在客户端推送通知栏显示的昵称,并不是用户个人信息的昵称,开发者可以自定义该内容。长度不可超过 100 个字符。
支持以下字符集:
• 26 个小写英文字母 a-z;
• 26 个大写英文字母 A-Z;
• 10 个数字 0-9;
• 中文;
• 特殊字符。
activated 用户是否已激活,
true:已激活。
false:封禁,封禁需要通过解禁接口进行解禁,才能正常登录。

请求示例

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

响应示例

{  
  "action": "put",  
  "application": "8be024f0-e978-11e8-b697-5d598d5f8402",  
  "path": "/users",  
  "uri": "https://a1.easemob.com/easemob-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": "easemob-demo",  
"applicationName": "testapp"
}

响应码

响应码 意义
200 成功。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
400 用户不存在。
429 或者 5xx 被限流或者发生异常。

设置推送消息展示方式

设置推送消息至客户端的方式,修改后及时有效。服务端对应不同的设置,向用户发送不同展示方式的消息。

基本信息

方法:PUT

接入点:https://{host}/{org_name}/{app_name}/users/{username}

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯云控制台注册项目时所在的集群服务器地址
org_name String 必需 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。
username String 必须 用户名。

请求头

参数 类型 是否必需 描述
Content-Type String 必需 内容类型:application/json
Authorization String 必需 Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

请求体

参数 类型 是否必需 说明
notification_display_style string 必需 消息提醒方式,
0:仅通知;
1:通知以及消息详情,没有设置返不会返回。

响应体

参数 说明
uuid 用户的 UUID,即系统为用户生成唯一标识字段,开发者可以不用关注。
type “user” 用户类型。
username 用户名,也就是环信用户 ID。
activated 用户是否已激活
true:已激活。
false:封禁,封禁需要通过解禁接口进行解禁,才能正常登录。
notification_display_style 消息提醒方式,
•“0”:仅通知;
•“1“:通知以及消息详情,没有设置返不会返回。

请求示例

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

响应示例

{  
  "action" : "put",  
  "application" : "17d59e50-0aee-11e8-8092-0dc80c0f5e99",  
  "path" : "/users",  
  "uri" : "https://a1.easemob.com/easemob-demo/testapp/users",  
  "entities" : [ 
    {    
      "uuid" : "3b8c9890-7b9a-11e8-9d88-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"
}

响应码

响应码 意义
200 成功。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
429 或者 5xx 被限流或者发生异常。

设置推送免打扰

设置推送用户免打扰,在免打扰的时间段内,用户将不会收到离线消息推送。

基本信息

方法:PUT

接入点:https://{host}/{org_name}/{app_name}/users/{username}

请求头

参数 类型 是否必需 描述
Content-Type String 必需 内容类型:application/json
Authorization String 必需 Bearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

请求体

参数 类型 是否必需 描述
notification_no_disturbing boolean 必需 是否设置免打扰。
true:是。
false:否。
notification_no_disturbing_start string 必需 免打扰开始时间,UTC 时间,单位为小时,取值范围 [0-24]。例如 “8” 代表每日 8:00 开启免打扰。
notification_no_disturbing_end string 必需 免打扰结束时间,UTC 时间,单位为小时,取值范围 [0-24]。例如 “18” 代表每日 18:00 结束免打扰。

响应体

参数 说明
uuid 用户的 UUID,即系统为用户生成唯一标识字段,开发者可以不用关注。
type “user” 用户类型。
username 用户名,也就是环信用户 ID。
activated 用户是否已激活。
true:已激活。
false:封禁,封禁需要通过解禁接口进行解禁,才能正常登录。
notification_display_style 消息提醒方式。
•“0”:仅通知;
•“1“:通知以及消息详情,没有设置返不会返回。
notification_no_disturbing_start 免打扰的开始时间。数字代表开始时间,例如 “8” 代表每日 8:00 开启免打扰。
notification_no_disturbing_end 免打扰的结束时间。数字代表结束时间,例如 “18” 代表每日 18:00 关闭免打扰。

请求示例

设置免打扰时间

curl -X PUT -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EKeAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFDSEF2E" -i  "https://a1.easemob.com/easemob-demo/testapp/users/a " -d '{"notification_no_disturbing": true,"notification_no_disturbing_start": "1","notification_no_disturbing_end": "3"}'

取消免打扰

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

响应示例

{  
  "action" : "put",  
  "application" : "17d59e50-0aee-11e8-8092-0dc80c0f5e99",  
  "path" : "/users",  
  "uri" : "https://a1.easemob.com/easemob-demo/testapp/users",  
  "entities" : [ 
    {    
    "uuid" : "3b8c9890-7b9a-11e8-9d88-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"
}

响应码

响应码 意义
200 成功。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
429 或者 5xx 被限流或者发生异常。