发送推送通知

大约 14 分钟

发送推送通知

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

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

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

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

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

公共参数

请求参数

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

响应参数

参数类型描述
timestampLongUnix 时间戳,单位为毫秒。
durationInt从发送请求到响应的时长,单位为毫秒。

认证方式

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

Authorization:Bearer ${YourAppToken}

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

以同步方式发送推送通知

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

提示

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

HTTP 请求

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

路径参数

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

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

请求 header

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

请求 body

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

HTTP 响应

响应 body

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

字段类型描述
dataObject推送结果。服务器根据推送结果判断推送状态。
data.pushStatusString推送状态:
- 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": "环信",
      }
}'

响应示例

  1. 推送成功的示例如下:
{
    "timestamp": 1689154498019,
    "data": [
       {
            "pushStatus": "SUCCESS",
            "data": {
                "code": 200,
                "data": {
                    "expireTokens": [],
                    "sendResult": true,
                    "requestId": "104410638-fd96648b6bb4344bc4f5e29b158fdb07",
                    "failTokens": [],
                    "msgCode": 200
               },
                "message": "Success"
           }
       }
   ],
    "duration": 2
}
  1. 因未绑定推送信息导致推送失败的响应示例:
{
    "timestamp": 1689154624797,
    "data": [
       {
            "pushStatus": "FAIL",
            "desc": "no push binding"
       }
   ],
    "duration": 0
}
  1. 因接收推送通知的用户 ID 不存在导致推送失败的响应示例:
{
    "timestamp": 1689154534352,
    "data": [
       {
            "pushStatus": "FAIL",
            "desc": "appUser not exists"
       }
   ],
    "duration": 0
}

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

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

HTTP 请求

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

路径参数

参数及描述详见 公共参数

请求 header

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

请求 body

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

HTTP 响应

响应 body

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

字段类型描述
dataObject异步推送的结果,即成功或失败。
idString推送的目标用户 ID。
pushStatusString推送状态:ASYNC_SUCCESS 表示推送成功。
descString推送结果的相关描述。

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

如果返回的 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-TypeString内容类型:application/json
AuthorizationStringBearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

请求 body

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

HTTP 响应

响应 body

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

字段类型描述
dataObject推送任务数据。
taskIdLong推送任务 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-TypeString内容类型:application/json
AuthorizationStringBearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。

请求 body

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

HTTP 响应

响应 body

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

参数类型说明
dataLong推送任务 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
}

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

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

  1. 创建推送通知;
  2. 创建全量推送任务或者创建列表推送任务。

创建推送通知

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

HTTP 请求

POST https://{host}/{org_name}/{app_name}/push/message
路径参数

参数及说明详见 公共参数

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

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

HTTP 响应

响应 body

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

参数类型说明
dataLong创建推送通知时后台生成的消息 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}
路径参数
参数类型描述是否必需
messageIdString推送通知 ID,创建推送通知时返回。

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

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

HTTP 响应

响应 body

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

参数类型描述
dataString推送通知的内容。

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

如果返回的 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-TypeString内容类型:application/json
AuthorizationStringBearer ${YourAppToken} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。
请求 body
字段类型描述是否必需
strategyInt推送策略:
- 0:厂商通道优先,失败时走环信通道。
- 1:在线或者离线推送都走环信通道。该情况下,若用户在线,则直接推送;若用户离线,消息保留 7 天,超过该期限则丢弃消息。
-(默认)2:只通过第三方厂商推送。若用户离线,消息保留时间视不同厂商而定。若推送失败,直接丢弃推送消息。
- 3:环信通道优先,在线推送走环信通道,离线推送走厂商通道。如果厂商推送失败,则等待用户上线后通过环信通道下发。
- 4:仅走环信通道且只推在线用户,离线用户收不到推送通知。
pushMsgIdLong推送通知 ID。

HTTP 响应

响应 body

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

字段类型描述
dataString推送任务 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
}
上次编辑于: