使用文档

推送服务可以通过 REST API 接口进行使用。

环信 REST API 介绍,请参考:https://docs-im.easemob.com/im/server/ready/intro

环信即时推送与环信即时通讯 IM 服务使用一套用户体系,用户体系相关接口,请查看:https://docs-im.easemob.com/im/server/ready/user

接口描述

通过 REST 使用即时推送服务有两种方式:1.使用单接口批量发送推送消息,2.通过接口组合发送推送消息。

通过接口组合发送推送的流程

  1. 创建推送消息。
  2. 创建全局推送任务或者创建列表推送任务。

** 注意:推送任务最多 3 个同时进行,否则接口调用时会报错!**

全局推送和列表推送均会创建任务,而推送任务的创建是有时间限制的,推送任务数限制如下:
1、五分钟内限制创建任务数为3,可配置;
2、全局推送创建任务后,限制数增加1,未开始执行的也记录;
3、标签/列表推送创建任务后,限制数加1,执行完成后,限制数减1;
4、所有限制均为5分钟,后续可以继续创建。

请求头参数

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

路径参数

参数 是否必需 类型 描述
org_name 必需 String 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过环信即时通讯云控制台获取该字段,详见获取即时通讯项目信息。
app_name 必需 String 即时通讯服务分配给每个 app 的名称。你可以通过环信即时通讯云控制台获取该字段,详见获取即时通讯项目信息。
username 必需 String 用户 ID。用户的唯一登录账号。长度在 64 个字符内,不可设置为空。
host 必需 String 即时通讯服务器集群地址,你可以通过环信即时通讯云控制台获取该字段,详见获取即时通讯项目信息。

响应体参数

参数 描述
action 请求方式,即接口方法名。
organization 组织名称,即 org_name
application 系统内为应用生成的唯一标识,无需关注。
applicationName app 名称,即 app_name,每个 app 的名称。
appkey 应用的 App Key。你可以通过环信即时通讯云控制台获取该字段,详见获取即时通讯项目信息。
uri 请求 URL。
path 请求路径,属于请求 URL 的一部分,开发者无需关注。
entities 详细信息。
uuid 用户的 UUID。系统为该请求中的用户生成唯一内部标识,无需关注。
type 对象类型。无需关注。
created 注册用户的 Unix 时间戳(毫秒)。
modified 最近一次修改用户信息的 Unix 时间戳(毫秒)。
username 用户 ID。用户登录的唯一账号。
activated 用户是否已激活。
true:已激活。
false:封禁,封禁需要通过解禁接口进行解禁,才能正常登录。
timestamp 响应的 Unix 时间戳(毫秒)。
duration 从发送请求到响应的时长(毫秒)。

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

Authorization:Bearer ${YourAppToken}

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

单独为某些用户推送

使用该接口可以指定单个或批量用户 ID 进行消息推送。

注意 asynctrue 才允许批量推送。

方法:POST

接入点:{https://host}/{org_name}/{app_name}/push/single

请求体参数

字段 是否必需 类型 说明
targets 必需 list 推送目标用户 ID。最大可传 100 个。
async 非必需 bool 是否异步推送。
-(默认)true: 异步。推送目标数量为 100。
- false:同步推送,推送目标数量为 1。
strategy 非必需 integer 推送策略。说明:
- 0:厂商通道优先,失败时走环信通道。
- 1:在线或者离线都通过环信通道推送。
-(默认)2:只通过第三方厂商推送(失败后直接丢弃)。
- 3:环信通道优先,在线走环信,离线走厂商。
pushMessage 必需 JSON 推送消息。消息内容请查看:推送消息字段解释

响应参数

字段 类型 说明
id string 推送目标用户 ID。
pushStatus string 推送结果:
SUCCESS:推送成功;
FAIL:推送失败;
ERROR:推送异常;
ASYNC_SUCCESS:异步推送成功。
data JSON •同步推送:三方手机厂商返回推送结果
•异步推送:写异步消息结果。
desc string 推送结果描述。

请求示例

curl -X POST "http://localhost:8099/easemob-demo/testy/push/single" -H "Authorization: Bearer YWMtOzQVjJ3mEeuJQv1qXhB5QAAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF41YIKUABPGgDuIZeu5IMVC_M9G5JlTjUsZeYVSg5o8BwshLgWveZxjA" -H "Content-Type: application/json" --data-raw "{
    \"targets\": [
        \"test2\"
    ],
    \"pushMessage\": {
        \"title\": \"你好\",
        \"subTitle\": \"你好\",
        \"content\": \"你好\",
        \"vivo\": {
 
        }
    }
}"

响应示例

{
    "timestamp": 1619506344007,
    "data": [
        {
            "id": "test2",
            "pushStatus": "ASYNC_SUCCESS",
            "desc": "async success."
        }
    ],
    "duration": 14
}

响应码

状态码 描述
200 请求成功。
400 请求参数错误,请根据返回提示检查。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
429,503 或者其他 5xx 单位时间内请求过多,请稍后重试。
500 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。

通过接口组合发送推送,应按照如下流程:

  1. 创建推送消息;
  2. 创建全局推送任务或者创建列表推送任务。

创建推送消息

创建推送消息并记录返回结果中的推送消息 ID,创建推送任务需要携带推送消息 ID。

方法:POST

接入点:https://{host}/{org_name}/{app_name}/push/message

请求体参数

消息内容请查看:推送消息字段解释

响应体参数

参数 说明
data 创建推送消息时后台生产的消息 ID,需要保存,创建推送任务是基于此 ID。

请求示例

curl -X POST "http://localhost:8099/easemob-demo/testy/push/message" -H "Authorization: Bearer YWMtOzQVjJ3mEeuJQv1qXhB5QAAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF41YIKUABPGgDuIZeu5IMVC_M9G5JlTjUsZeYVSg5o8BwshLgWveZxjA" -H "Content-Type: application/json" --data-raw "{
    \"title\": \"你好\",
    \"subTitle\": \"你好\",
    \"content\": \"你好\",
    \"vivo\": {}
}"

响应示例

{
    "timestamp": 1618817127903,
    "data": 833724991672734897,
    "duration": 0
}

响应码

状态码 描述
200 请求成功。
400 请求参数错误,请根据返回提示检查。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
429,503 或者其他 5xx 单位时间内请求过多,请稍后重试。
500 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。

查询推送消息

查询推送消息信息。

方法:GET

接入点:https://{host}/{org_name}/{app_name}/push/message/{messageId}

路径参数

字段 是否必需 类型 备注
messageId 必需 string 推送消息 ID。由创建推送消息返回。
host 必需 String 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name String 必需 你在环信即时通讯云控制台注册项目时填入的公司(组织)名称。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。

响应体参数

参数 说明
data 推送消息内容。

请求示例

curl -X GET "http://localhost:8099/easemob-demo/testy/push/message/832655326988867864" -H "Authorization: Bearer YWMtOzQVjJ3mEeuJQv1qXhB5QAAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF41YIKUABPGgDuIZeu5IMVC_M9G5JlTjUsZeYVSg5o8BwshLgWveZxjA"

响应示例

{
    "timestamp": 1618922805143,
    "data": {
        "appkey": "easemob-demo#testy",
        "timestamp": 1618922805091,
        "title": "你好1234",
        "subTitle": "你好",
        "content": "你好",
        "vivo": {}
    },
    "duration": 17
}

响应码

状态码 描述
200 请求成功。
400 请求参数错误,请根据返回提示检查。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
429,503 或者其他 5xx 单位时间内请求过多,请稍后重试。
500 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。

创建全局推送任务

创建推送消息,得到推送消息 ID,再通过创建全局推送任务进行全局消息推送。

基本信息

方法:POST

接入点:https://{host}/{org_name}/{app_name}/push/task/broadcast

路径参数

字段 是否必需 类型 备注
host 必需 String 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name String 必需 你在环信即时通讯云控制台注册项目时填入的公司(组织)名称。
app_name String 必需 你在环信即时通讯云控制台注册项目时填入的应用名称。

请求体参数

字段 是否必需 类型 备注
type 必需 string 推送对象(IM)目前只支持 Chat。
strategy 非必需 integer 推送策略。
- 0:厂商通道优先,失败时走环信通道。
- 1:在线或者离线都通过环信通道推送。
-(默认)2:只通过第三方厂商推送(失败后直接丢弃)。
- 3:环信通道优先,在线走环信,离线走厂商。
pushFunc 必需 string 推送方式(ALL)目前只支持全部推送(后续会增加组推送等)
pushMsgId 必需 long 推送消息 ID。

响应体参数

参数 说明
data 创建推送任务时后台生产的推送任务 ID(查询推送结果需要使用推送 ID)。

请求示例

curl -X POST "http://localhost:8099/easemob-demo/testy/push/task/broadcast" -H "Content-Type: application/json" --data-raw "{
    \"type\": \"IM\",
    \"pushFunc\": \"ALL\",
    \"pushMsgId\": 832253695868580464
}"

响应示例

{
    "timestamp": 1618817591755,
    "data": 833726937301309957,
    "duration": 1
}

响应码

状态码 描述
200 请求成功。
400 请求参数错误,请根据返回提示检查。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
429,503 或者其他 5xx 单位时间内请求过多,请稍后重试。
500 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。

创建推送任务

本接口为预留接口,后续将支持不同类型的推送模式,目前只支持全部推送。

方法:POST

接入点:{https://host}/{org_name}/{app_name}/push/task

路径参数

字段 是否必需 类型 备注
host 必需 String 你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |
org_name 必需 String 你在环信即时通讯云控制台注册项目时填入的公司(组织)名称。
app_name 必需 String 你在环信即时通讯云控制台注册项目时填入的应用名称。

请求体参数

字段 是否必需 类型 备注
type 非必需 string 推送对象(IM)目前只支持IM。
strategy 非必需 integer 推送策略。
- 0:厂商通道优先,失败时走环信通道。
- 1:在线或者离线都通过环信通道推送。
-(默认)2:只通过第三方厂商推送(失败后直接丢弃)。
- 3:环信通道优先,在线走环信,离线走厂商。
pushFunc 非必需 string 推送方式(ALL)目前只支持全部推送(后续会增加组推送等)。
pushMessage 必需 JSON 推送消息。

响应参数

参数 说明
data 推送任务 ID(后续相关推送结果都是基于任务的,需要保存)。

请求示例

curl -X POST "http://localhost:8099/easemob-demo/testy/push/task" -H "Content-Type: application/json" --data-raw "{
    \"typs\": \"IM\",
    \"pushFunc\": \"ALL\",
    \"pushMessage\": {
        \"title\": \"你好1234\",
        \"subTitle\": \"你好\",
        \"content\": \"你好\",
        \"vivo\": {}
    }
}"

响应示例

{
    "timestamp": 1618817591755,
    "data": 833726937301309957,
    "duration": 1
}

响应码

状态码 描述
200 请求成功。
400 请求参数错误,请根据返回提示检查。
401 鉴权失败(无 token,token 错误或者过期),请重新获取 token 再试。
429,503 或者其他 5xx 单位时间内请求过多,请稍后重试。
500 服务器内部错误,一般是 mysql 错误。如果问题持续存在,请联系我们的技术支持团队。

标签推送

使用标签推送即给单个标签内的所有用户 ID 推送消息。

方法:POST

接入点:{host}/{org}/{app}/push/list

请求体参数

字段 是否必需类型 说明
targets 必需 list 标签名称。最大可传 1 个。
pushFunc 必需 string 推送类型:LABEL:标签推送。
strategy 非必需 integer推送策略。说明:
- 0:厂商通道优先,失败时走环信通道。
- 1:在线或者离线都通过环信通道推送。
-(默认)2:只通过第三方厂商推送(失败后直接丢弃)。
- 3:环信通道优先,在线走环信,离线走厂商。
pushMessage必需 JSON 推送消息。消息内容请查看:推送消息字段解释

请求示例

curl -L -X POST 'http://a1-hsb.easemob.com/easemob-demo/easeim/push/list' \
-H 'Authorization: Bearer YWMtIPBHKsOyEeAAAAAAAAAAAExCXvf5bRGAJBgXNYFJVQ9AQMAAAGAWu67KQBPGgBOV9ghkGKbtt9H9b1' \
-H 'Content-Type: application/json' \
--data-raw '{
    "targets": [
        "90后"
    ],
    "pushFunc":"LABEL",
    "strategy": 2,
    "pushMessage": {
        "title": "环信 PUSH",
        "content": "欢迎使用环信推送服务",
        "sub_title": "环信"
    }
}'

响应示例

{
    "timestamp": 1650859482843,
    "data": {
        "taskId": 968120369184112182
    },
    "duration": 0
}