批量单推 API | WebPush 开发者指南 REST API 简体中文

示例使用新加坡地址。调用前，请根据应用所属数据中心选择对应 Base URL；分组推送须使用分组所属数据中心及该分组的凭据。地址列表见 REST API 概述.

功能说明

用于批量单推消息，一次调用可对多个目标用户推送消息。支持通过 registration_id 或 alias 推送：

通过 registration_id 推送： POST /v4/batch/push/regid
通过 alias 推送： POST /v4/batch/push/alias
能力限制：
- 单次请求最多支持 500 个推送目标
- 支持并发处理，提升效率
- 限流时返回部分成功结果
- 该API和Push API共用QPS配额，使用批量单推接口推送 1 个regid 或者 1 个alias，消耗 Push API 的QPS配额是1。

调用验证

在 HTTP Header 中添加鉴权字段：

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

此代码块在浮窗中显示

生成方式： base64(username:password)
- username = 应用 AppKey
- password = Master Secret
获取路径： 控制台 → 应用设置 → 应用信息

调用地址

通过 registration_id 批量推送

POST /v4/batch/push/regid

              
              POST /v4/batch/push/regid

此代码块在浮窗中显示

通过 alias 批量推送

POST /v4/batch/push/alias

              
              POST /v4/batch/push/alias

此代码块在浮窗中显示

请求示例

1. 通过 registration_id 批量推送

curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/regid \ -H "Content-Type: application/json" \ -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \ -d '{ "requests": [ { "target": "registration_id_1", "platform": "web", "notification": { "alert": "Hi,Push !", "web": { "alert": "Hi,Push !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false }, "custom_args": { "business": "info" } }, { "target": "registration_id_2", "platform": "web", "notification": { "alert": "Hi,MTPush !", "web": { "alert": "Hi,MTPush !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/regid \
  -H "Content-Type: application/json" \
  -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
  -d '{
    "requests": [
      {
        "target": "registration_id_1",
        "platform": "web",
        "notification": {
            "alert": "Hi,Push !",
            "web": {
                "alert": "Hi,Push !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        },
        "custom_args": {
          "business": "info"
        }
      },
      {
        "target": "registration_id_2",
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",
            "web": {
                "alert": "Hi,MTPush !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        }
      }
    ]
  }'

此代码块在浮窗中显示

2. 通过 alias 批量推送

curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/alias \ -H "Content-Type: application/json" \ -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \ -d '{ "requests": [ { "target": "user_alias_1", "platform": "web", "notification": { "alert": "Hi,Push !", "web": { "alert": "Hi,Push !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false } }, { "target": "user_alias_2", "platform": "web", "notification": { "alert": "Hi,MTPush !", "web": { "alert": "Hi,MTPush !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/alias \
  -H "Content-Type: application/json" \
  -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
  -d '{
    "requests": [
      {
        "target": "user_alias_1",
        "platform": "web",
        "notification": {
            "alert": "Hi,Push !",
            "web": {
              "alert": "Hi,Push !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        }
      },
      {
        "target": "user_alias_2",
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",
            "web": {
              "alert": "Hi,MTPush !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        }
      }
    ]
  }'

此代码块在浮窗中显示

请求参数

请求体结构：

{ "requests": [ { "target": "string", // 必填，推送目标（registration_id 或 alias） "platform": "string", // 必填，推送平台设置（参考推送 API） "notification": "object", // 可选，通知内容（参考推送 API） "message": "object", // 可选，自定义消息（参考推送 API），与notification不能并存 "options": "object", // 可选，推送选项（参考推送 API） "custom_args": "object" // 可选，透传给客户端的参数 } ] }

              
              {  
  "requests": [  
    {  
      "target": "string",     // 必填，推送目标（registration_id 或 alias）  
      "platform": "string",   // 必填，推送平台设置（参考推送 API）
      "notification": "object",  // 可选，通知内容（参考推送 API）  
      "message": "object",     // 可选，自定义消息（参考推送 API），与notification不能并存 
      "options": "object",     // 可选，推送选项（参考推送 API）  
      "custom_args": "object"  // 可选，透传给客户端的参数  
    }  
  ]  
}

此代码块在浮窗中显示

参数说明：

字段	必填	类型	说明
`requests`	是	array	批量请求数组（最多 500 个，同一批次内 `target` 不可重复）
`target`	是	string	目标值： - `/regid` 接口：`registration_id` - `/alias` 接口：`alias`
`platform`	是	string	WebPush 使用 `web` 或 `all`；在 WebPush 应用中，`all` 表示 Web 平台。
`notification`	否	object	通知内容（结构同推送 API）
`message`	否	object	自定义消息（结构同推送 API）
`options`	否	object	推送选项（如 `time_to_live`、`apns_production`）
`custom_args`	否	object	自定义透传参数

返回示例

成功响应（全部成功）

{ "results": { "registration_id_1": { "target": "registration_id_1", "success": true, "msg_id": 2460001 }, "registration_id_2": { "target": "registration_id_2", "success": true, "msg_id": 2460002 } } }

              
              {
  "results": {
    "registration_id_1": {
      "target": "registration_id_1",
      "success": true,
      "msg_id": 2460001
    },
    "registration_id_2": {
      "target": "registration_id_2",
      "success": true,
      "msg_id": 2460002
    }
  }
}

此代码块在浮窗中显示

HTTP 200 响应（存在逐项限流）

以下示例为进入批量处理后，部分目标超过可用配额的情况。外层 HTTP 状态为 200，不代表所有目标都成功。

HTTP/1.1 200 OK Content-Type: application/json

              
              HTTP/1.1 200 OK
Content-Type: application/json

此代码块在浮窗中显示

{ "rate_limit_info": { "message": "Some requests were rate limited during batch processing", "rate_limit_occurred": true }, "results": { "170976fa8a0771c2647": { "target": "170976fa8a0771c2647", "success": false, "error": { "code": 23008, "message": "API rate limit exceeded" } }, "170976fa8a9277c25d4": { "target": "170976fa8a9277c25d4", "success": true, "msg_id": 2460002 } } }

              
              {
    "rate_limit_info": {
        "message": "Some requests were rate limited during batch processing",
        "rate_limit_occurred": true
    },
    "results": {
        "170976fa8a0771c2647": {
            "target": "170976fa8a0771c2647",
            "success": false,
            "error": {
                "code": 23008,
                "message": "API rate limit exceeded"
            }
        },
        "170976fa8a9277c25d4": {
            "target": "170976fa8a9277c25d4",
            "success": true,
            "msg_id": 2460002
        }
    }
}

此代码块在浮窗中显示

失败响应（全局错误）

{ "error": { "code": 21004, "message": "basic auth failed" } }

              
              {  
  "error": {  
    "code": 21004,  
    "message": "basic auth failed"  
  }  
}

此代码块在浮窗中显示

失败响应（参数错误）

{ "error": { "code": 21003, "message": "Parameter value is invalid" } }

              
              {  
  "error": {  
    "code": 21003,  
    "message": "Parameter value is invalid"  
  }  
}

此代码块在浮窗中显示

错误码说明

下表未另行注明的 HTTP 状态码适用于请求级错误；逐项错误在 results[目标].error 中返回，外层 HTTP 状态仍为 200。

错误码	说明	处理方式	HTTP状态码
全局错误码
21004	Basic 鉴权失败	检查 AppKey/MasterSecret	401
21008	AppKey 长度非 24 位	验证 AppKey 格式	400
21038	应用无推送权限	检查应用配置	400
21043	应用无推送权限（存在待补缴账单）	处理账单	400
23009	IP 不在白名单	添加服务器 IP 到白名单	400
21009	系统内部错误（不可重试）	联系技术支持	400
限流错误码
23008	API 限流	部分成功时重试失败项	400（请求级）；200（逐项结果）
参数错误码
21003	参数值不合法	检查请求体格式	400
21015	请求参数错误	验证必填字段	400
21016	参数校验失败	检查字段类型和取值范围	400

完整错误码参考：创建推送 API - 调用返回

注意事项

限流处理： 请求整体限流返回 HTTP 400；进入批量处理后的逐项限流在 HTTP 200 的 results 中返回 success=false 和 error.code=23008，仅重试失败项。
重复检查： 同一批次内所有 target和cid 必须唯一。
数量限制： 单次请求不超过 500 个目标。
错误处理： 全局错误（如鉴权失败）会立即中断，不返回部分结果。