发送推送通知

大约 14 分钟

发送推送通知

利用 REST 接口可通过以下三种方式使用即时推送服务：

使用单接口批量发送推送通知。
通过接口组合发送推送通知，即先创建推送通知，然后创建全量推送任务或者创建列表推送任务。
通过推送标签发送推送通知。

注意：推送任务最多 3 个同时进行，否则接口调用时会报错！

全量推送和列表推送均会创建任务，而推送任务的创建是有时间限制的，推送任务数限制如下：

五分钟内限制创建任务数为 3，可配置；5 分钟内最多可创建 3 个任务。如果超过该任务数，请联系商务。
全量推送创建任务后，限制数增加1，未开始执行的也记录；
标签/列表推送创建任务后，限制数加1，执行完成后，限制数减1；
所有限制均为 5 分钟，后续可以继续创建。

公共参数

请求参数

参数	类型	是否必需	描述
`host`	String	是	访问 RESTful API 的域名或服务器信息。 -公有云集成为环信即时通讯控制台的 `即时通讯->服务概览`页面下的 `域名配置- Rest Api`。 -私有化集成为部署后 `服务器地址:端口`。
`org_name`	String	是	每个公司（组织）分配的唯一标识。详见环信即时通讯控制台的 `应用概览->应用详情`页面下的 `应用信息-Orgname`。
`app_name`	String	是	创建应用时填入的应用名称。详见环信即时通讯控制台的 `应用概览->应用详情`页面下的 `应用信息-Appname`。
`username`	String	是	用户 ID。

响应参数

参数	类型	描述
`timestamp`	Long	Unix 时间戳，单位为毫秒。
`duration`	Int	从发送请求到响应的时长，单位为毫秒。

认证方式

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

Authorization：Bearer ${YourAppToken}

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

以同步方式发送推送通知

调用该接口以同步方式推送消息时，环信或第三方推送厂商在推送消息后，会将推送结果发送给环信服务器。服务器根据收到的推送结果判断推送状态。

提示

该接口调用频率默认为 1 次/秒。
建议在开发环境中进行调试时使用该接口。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/push/sync/{target}

路径参数

参数	类型	描述	是否必需
`target`	String	接收推送通知的用户 ID。	是

其他参数及描述详见公共参数。

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

请求 body

字段	类型	描述	是否必需
`strategy`	Int	推送策略： -`0`：厂商通道优先，失败时走环信通道。 - `1`：在线或者离线推送都走环信通道。若用户在线，则直接推送；若用户离线，消息会保留一段时间（视版本而定），超过该期限则丢弃消息。 -（默认）`2`：只走第三方厂商推送。若用户离线，消息保留时间视不同厂商而定。若推送失败，直接丢弃推送消息。 - `3`：环信通道优先，在线推送走环信通道，离线推送走厂商通道。如果厂商推送失败，则等待用户上线后通过环信通道下发。 - `4`：仅走环信通道且只推在线用户，离线用户收不到推送通知。	否
`pushMessage`	JSON	推送通知。关于通知内容，请查看配置推送通知。	是

HTTP 响应

响应 body

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

字段	类型	描述
`data`	Object	推送结果。服务器根据推送结果判断推送状态。
`data.pushStatus`	String	推送状态： - `SUCCESS`：推送成功； - `FAIL`：推送失败，即非服务端导致的错误，例如 `bad device token`，表示移动端传给服务端的 device token 错误，对应推送厂商不接受。 - `ERROR`：推送异常，即服务端导致错误，例如连接超时或读写超时。

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

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

示例

请求示例

curl -X POST 'http://XXXX/XXXX/XXXX/push/sync/test1' \
-H 'Authorization: Bearer <YourAppToken>' \
-H 'Content-Type: application/json' \
-d '{
    "strategy": 3,
    "pushMessage": {
        "title": "环信推送",
        "content": "你好，欢迎使用环信推送服务",
        "sub_title": "环信",
      }
}'

响应示例

推送成功的示例如下：

{
    "timestamp": 1689154498019,
    "data": [
       {
            "pushStatus": "SUCCESS",
            "data": {
                "code": 200,
                "data": {
                    "expireTokens": [],
                    "sendResult": true,
                    "requestId": "104410638-fd96648b6bb4344bc4f5e29b158fdb07",
                    "failTokens": [],
                    "msgCode": 200
               },
                "message": "Success"
           }
       }
   ],
    "duration": 2
}

因未绑定推送信息导致推送失败的响应示例：

{
    "timestamp": 1689154624797,
    "data": [
       {
            "pushStatus": "FAIL",
            "desc": "no push binding"
       }
   ],
    "duration": 0
}

因接收推送通知的用户 ID 不存在导致推送失败的响应示例：

{
    "timestamp": 1689154534352,
    "data": [
       {
            "pushStatus": "FAIL",
            "desc": "appUser not exists"
       }
   ],
    "duration": 0
}

使用单接口批量发送推送通知

你可以为指定的单个或多个用户进行消息推送。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/push/single

路径参数

参数及描述详见公共参数。

请求 header

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

请求 body

字段	类型	描述	是否必需
`targets`	List	推送的目标用户 ID。最多可传 100 个。	是
`strategy`	Int	推送策略： -`0`：厂商通道优先，失败时走环信通道。 - `1`：在线或者离线推送都走环信通道。若用户在线，则直接推送；若用户离线，消息保留 7 天，超过该期限则丢弃消息。 -（默认）`2`：只走第三方厂商推送。若用户离线，消息保留时间视不同厂商而定。若推送失败，直接丢弃推送消息。 - `3`：环信通道优先，在线推送走环信通道，离线推送走厂商通道。如果厂商推送失败，则等待用户上线后通过环信通道下发。 - `4`：仅走环信通道且只推在线用户，离线用户收不到推送通知。	否
`pushMessage`	JSON	推送通知。关于通知内容，请查看配置推送通知。	是

HTTP 响应

响应 body

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

字段	类型	描述
`data`	Object	异步推送的结果，即成功或失败。
`id`	String	推送的目标用户 ID。
`pushStatus`	String	推送状态：`ASYNC_SUCCESS` 表示推送成功。
`desc`	String	推送结果的相关描述。

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

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

示例

请求示例

curl -X POST "http://localhost:8099/easemob-demo/testy/push/single" 
-H "Authorization: Bearer <YourAppToken> -H "Content-Type: application/json" -d '{
    "targets": [
        "test2"
    ],
    "pushMessage": {
        "title": "Hello",
        "subTitle": "Hello",
        "content": "Hello",
        "vivo": {
 
        }
    }
}'

响应示例

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

使用标签推送接口发送推送通知

向单个标签内的所有用户推送通知。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/push/list/label

路径参数

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

请求 header

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

请求 body

字段	类型	描述	是否必需
`targets`	List	标签名称。只支持传入单个标签名称。	是
`strategy`	Int	推送策略： - `0`：厂商通道优先，失败时走环信通道。 - `1`：在线或者离线都通过环信通道推送。若用户在线，则直接推送；若用户离线，消息保留 7 天，超过该期限则丢弃消息。 -（默认）`2`：只通过第三方厂商推送。若用户离线，消息保留时间视不同厂商而定。若推送失败，直接丢弃推送消息。 - `3`：环信通道优先，在线推送走环信通道，离线推送走厂商通道。如果厂商推送失败，则等待用户上线后通过环信通道下发。 - `4`：仅走环信通道且只推在线用户，离线用户收不到推送通知。	否
`pushMessage`	JSON	推送通知。关于通知的内容，请参考配置推送通知。	是

HTTP 响应

响应 body

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

字段	类型	描述
`data`	Object	推送任务数据。
`taskId`	Long	推送任务 ID。

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

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

示例

请求示例

curl -L -X POST 'http://a1.easemob.com/easemob/easeim/push/list/label' \
-H 'Authorization: Bearer YWMtIPBHKsOyEeAAAAAAAAAAAExCXvf5bRGAJBgXNYFJVQ9AQMAAAGAWu67KQBPGgBOV9ghkGKbtt9H9b1' \
-H 'Content-Type: application/json' \
--data-raw '{
    "targets": [
        "post-90s"
    ],
    "strategy": 2,
    "pushMessage": {
        "title": "Easemob PUSH",
        "content": "Welcome to Easemob Push Service",
        "sub_title": "Easemob"
    }
}'

响应示例

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

创建全量推送任务

每次调用该接口，服务端会创建一个推送任务，生成推送任务 ID，用于推送任务的数据统计。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/push/task

路径参数

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

请求 header

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

请求 body

字段	是否必需	类型	备注
`strategy`	非必需	integer	推送策略。 - `0`：厂商通道优先，失败时走环信通道。 - `1`：在线或者离线都通过环信通道推送。若用户在线，则直接推送；若用户离线，消息保留 7 天，超过该期限则丢弃消息。 -（默认）`2`：只通过第三方厂商推送。若用户离线，消息保留时间视不同厂商而定。若推送失败，直接丢弃推送消息。 - `3`：环信通道优先，在线推送走环信通道，离线推送走厂商通道。如果厂商推送失败，则等待用户上线后通过环信通道下发。 - `4`：仅走环信通道且只推在线用户，离线用户收不到推送通知。
`pushMessage`	必需	JSON	推送通知。

HTTP 响应

响应 body

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

参数	类型	说明
`data`	Long	推送任务 ID（后续相关推送结果都是基于任务的，需要保存）。

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

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

示例

请求示例

curl -X POST "http://localhost:8099/easemob-demo/testy/push/task" -H "Content-Type: application/json" --data-raw '{
    "pushMessage": {
        "title\": "Hello1234",
        "subTitle": "Hello",
        "content": "Hello",
        "vivo": {}
    }
}'

响应示例

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

通过接口组合发送全量推送通知

通过接口组合发送全量推送，应按照如下流程：

创建推送通知；
创建全量推送任务或者创建列表推送任务。

创建推送通知

创建推送通知并记录返回结果中的推送通知 ID，创建推送任务需要携带推送通知 ID。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/push/message

路径参数

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

请求 header

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

请求 body

关于消息内容，请查看配置推送通知。

HTTP 响应

响应 body

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

参数	类型	说明
`data`	Long	创建推送通知时后台生成的消息 ID，需要保存，创建推送任务是基于此 ID。

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

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

示例

请求示例

curl -X POST "http://localhost:8099/easemob-demo/testy/push/message" 
-H "Authorization: Bearer YWMtOzQVjJ3mEeuJQv1qXhB5QAAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF41YIKUABPGgDuIZeu5IMVC_M9G5JlTjUsZeYVSg5o8BwshLgWveZxjA" 
-H "Content-Type: application/json" -d '{
    "title": "Hello",
    "subTitle": "Hello",
    "content": "Hello",
    "vivo": {}
}'

响应示例

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

查询推送通知

查询推送通知信息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/push/message/{messageId}

路径参数

参数	类型	描述	是否必需
`messageId`	String	推送通知 ID，创建推送通知时返回。	是

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

请求 header

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

HTTP 响应

响应 body

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

参数	类型	描述
`data`	String	推送通知的内容。

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

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

示例

请求示例

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": "Hello1234",
        "subTitle": "Hello",
        "content": "Hello",
        "vivo": {}
    },
    "duration": 17
}

创建全量推送任务

创建推送通知，得到推送通知 ID，然后创建全量推送任务进行全量消息推送。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/push/task/broadcast

路径参数

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

请求 header

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

请求 body

字段	类型	描述	是否必需
`strategy`	Int	推送策略： - `0`：厂商通道优先，失败时走环信通道。 - `1`：在线或者离线推送都走环信通道。该情况下，若用户在线，则直接推送；若用户离线，消息保留 7 天，超过该期限则丢弃消息。 -（默认）`2`：只通过第三方厂商推送。若用户离线，消息保留时间视不同厂商而定。若推送失败，直接丢弃推送消息。 - `3`：环信通道优先，在线推送走环信通道，离线推送走厂商通道。如果厂商推送失败，则等待用户上线后通过环信通道下发。 - `4`：仅走环信通道且只推在线用户，离线用户收不到推送通知。	否
`pushMsgId`	Long	推送通知 ID。	是

HTTP 响应

响应 body

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

字段	类型	描述
`data`	String	推送任务 ID（查询推送结果需要使用推送任务 ID）。

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

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

示例

请求示例

curl -X POST "http://localhost:8099/easemob-demo/testy/push/task/broadcast" 
-H "Content-Type: application/json" -d '{
    "pushMsgId": 832253695868580464
}'

响应示例

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

发送推送通知

# 发送推送通知

# 公共参数

# 请求参数

# 响应参数

# 认证方式

# 以同步方式发送推送通知

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 使用单接口批量发送推送通知

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 使用标签推送接口发送推送通知

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 创建全量推送任务

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 通过接口组合发送全量推送通知

# 创建推送通知

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 查询推送通知

# HTTP 请求

# 路径参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 创建全量推送任务

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

发送推送通知

公共参数

请求参数

响应参数

认证方式

以同步方式发送推送通知

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

使用单接口批量发送推送通知

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

使用标签推送接口发送推送通知

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

创建全量推送任务

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

通过接口组合发送全量推送通知

创建推送通知

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

查询推送通知

HTTP 请求

路径参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

创建全量推送任务

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例