发送推送通知

大约 15 分钟

发送推送通知

功能说明

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

推送任务说明

调用 全量推送 和 按标签推送 接口以及在 环信控制台创建推送任务 时，均会创建推送任务，受以下限制：

同一统计周期（5 分钟）内，推送任务的并发运行数为 3 个，超出则接口报错。如需提升上限，请联系环信商务。

不同任务类型对并发运行数的占用时长不同，具体规则如下：

任务类型创建时执行完成后并发运行数何时释放
- 接口调用：全量推送、按标签推送
- 控制台创建：全量推送任务、标签推送任务		计数 +1计数 -1执行完成后立即释放
控制台创建：向指定用户推送的任务计数 +1计数不变统计周期结束后统一释放

统计周期结束后，所有计数清零，进入下一个周期。

公共参数

请求参数

参数类型是否必需描述
hostString是环信即时通讯 IM 分配的用于访问 RESTful API 的域名。
org_nameString是环信即时通讯 IM 为每个公司（组织）分配的唯一标识。
app_nameString是你在环信控制台创建应用时填入的应用名称。
usernameString是用户 ID。

响应参数

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

认证方式

环信即时通讯 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}

路径参数

参数类型描述是否必需
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：推送异常，即服务端导致错误，例如连接超时或读写超时。
data.dataObject绑定推送信息对应平台返回的推送结果数据。
data.descString推送失败描述信息。

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

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

示例

请求示例

将 <YourAppToken> 替换为你在服务端生成的 App Token
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/async/{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.dataString推送通知的内容。
data.pushStatusString推送状态：ASYNC_SUCCESS 表示推送成功。
data.descString推送结果的相关描述。

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

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

示例

请求示例

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST 'http://XXXX/XXXX/XXXX/push/async/test1' \
-H 'Authorization: Bearer <YourAppToken>' \
-H 'Content-Type: application/json' \
-d '{
    "strategy": 3,
    "pushMessage": {
        "title": "环信推送",
        "content": "你好，欢迎使用环信推送服务",
        "sub_title": "环信"
     }
}'

响应示例

{
    "timestamp": 1723512536934,
    "data": [
       {
            "pushStatus": "ASYNC_SUCCESS",
            "data": "",
            "desc": "success"
       }
   ],
    "duration": 7
}

异步批量推送多用户

调用该接口以异步方式为指定的单个或多个用户进行消息推送。

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：只走环信通道：若用户在线，则直接推送；若用户离线，消息会保留一段时间（视购买的套餐包而定），等用户上线后向其推送消息。若用户在超过消息存储期限时仍未上线，则丢弃消息。
-（默认）2：只走第三方厂商通道：若用户离线，消息保留时间视不同厂商而定。若推送失败，直接丢弃推送消息。
- 3：在线走环信通道，离线走第三方厂商通道。如果厂商推送失败，则等待用户上线后通过环信通道下发。
- 4：只走环信通道且只推在线用户。离线用户收不到推送通知。		否
pushMessageJSON推送通知。关于通知内容，请查看 配置推送通知。是

HTTP 响应

响应 body

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

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

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

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

示例

请求示例

将 <YourAppToken> 替换为你在服务端生成的 App Token
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
}

按标签推送用户群

向单个标签内的所有用户推送通知或向多个标签下的交集用户推送通知。

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

HTTP 请求

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

路径参数

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

请求 header

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

请求 body

字段类型描述是否必需
targetsList标签名称:
- 若传入单个标签名称，则向该标签内的所有用户推送通知。
- 若传入多个标签名称（最多可传 5 个），则向这些标签下的交集用户推送通知。		是
startDateString推送任务开始时间，格式: yyyy-MM-dd HH:mm:ss，例如 2024-01-01 12:00:00。

提示

1. 定时时间只能是 1 小时之后，30 天之内。
2. 定时时间时区判定为服务器所在时区。如果跨服务器时区调用请注意计算准确时间。

否
strategyInt推送策略：
-0：第三方厂商通道优先，失败时走环信通道。
- 1：只走环信通道：若用户在线，则直接推送；若用户离线，消息会保留一段时间（视购买的套餐包而定），等用户上线后向其推送消息。若用户在超过消息存储期限时仍未上线，则丢弃消息。
-（默认）2：只走第三方厂商通道：若用户离线，消息保留时间视不同厂商而定。若推送失败，直接丢弃推送消息。
- 3：在线走环信通道，离线走第三方厂商通道。如果厂商推送失败，则等待用户上线后通过环信通道下发。
- 4：只走环信通道且只推在线用户。离线用户收不到推送通知。		否
pushMessageJSON推送通知。关于通知的内容，请参考配置推送通知。是

HTTP 响应

响应 body

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

字段类型描述
dataObject推送任务数据。
taskIdLong推送任务 ID。

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

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

示例

请求示例

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST 'http://a1.easemob.com/easemob/easeim/push/list/label' \
-H 'Authorization: Bearer <YourAppToken>' \
-H 'Content-Type: application/json' \
-d '{
    "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

字段是否必需类型备注
startDate否String推送任务开始时间，格式: yyyy-MM-dd HH:mm:ss，例如 2024-01-01 12:00:00。

提示

1. 设置的时间必须为当前时间的 1 小时之后，30 天之内。例如，如果当前时间为 2024-09-01 00:00:00，你设置的时间必须是 2024-09-01 01:00:00 及之后的时间，而且不能超过 2024-10-01 01:00:00。
2. 设置的时间的时区默认为服务器所在时区。如果跨服务器时区调用，请注意计算准确时间。

strategy否integer推送策略：
-0：第三方厂商通道优先，失败时走环信通道。
- 1：只走环信通道：若用户在线，则直接推送；若用户离线，消息会保留一段时间（视购买的套餐包而定），等用户上线后向其推送消息。若用户在超过消息存储期限时仍未上线，则丢弃消息。
-（默认）2：只走第三方厂商通道：若用户离线，消息保留时间视不同厂商而定。若推送失败，直接丢弃推送消息。
- 3：在线走环信通道，离线走第三方厂商通道。如果厂商推送失败，则等待用户上线后通过环信通道下发。
- 4：只走环信通道且只推在线用户。离线用户收不到推送通知。
pushMessage是JSON推送通知。

HTTP 响应

响应 body

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

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

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

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

示例

请求示例

将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST 'http://localhost:8099/easemob-demo/testy/push/task' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>'  \
-d '{
    "pushMessage": {
        "title": "Hello1234",
        "subTitle": "Hello",
        "content": "Hello",
        "vivo": {}
    }
}'

响应示例

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

常见错误码

调用发送推送通知相关的 REST API 时，若返回的 HTTP 状态码非 200，则请求失败，提示错误。本节列出这些接口的常见错误码。

HTTP 状态码错误类型错误提示可能原因处理建议
403ServiceNotOpenExceptionpush service not open即时推送功能未开通确认并开通即时推送功能。
403LimitExceptionlimit request因为数量或其他限制导致请求失败根据返回信息的限制原因处理。
400MessageExceptionbad_request推送消息配置错误检查并修改，使用正确的推送消息体。
400IllegalArgumentException任意推送参数配置错误检查并修改，使用正确的对应参数。
404请求路径不存在url is invalid请求路径错误检查并修改，使用正确的请求路径。
5xx服务器内部错误任意服务器在尝试处理请求时发生内部错误联系环信技术支持。

其他错误，你可以参考 错误码 了解可能的原因。

上次编辑于:
环信 IM 文档
© 环信 2026