批量单推 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://pushapi-sgp.engagelab.com/v4/batch/push/regid \ -H "Content-Type: application/json" \ -u "AppKey:MasterSecret" \ -d '{ "requests": [ { "target": "registration_id_1", "platform": "android", "notification": { "android": { "alert": "Hi, Push!", "title": "Send to Android", "builder_id": 1, "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false }, "custom_args": { "business": "info" } }, { "target": "registration_id_2", "platform": "ios", "notification": { "ios": { "alert": "Hi, MTPush!", "sound": "default", "badge": "+1", "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }

              
              curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/regid \  
  -H "Content-Type: application/json" \  
  -u "AppKey:MasterSecret" \  
  -d '{  
    "requests": [  
      {  
        "target": "registration_id_1",  
        "platform": "android",  
        "notification": {  
          "android": {  
            "alert": "Hi, Push!",  
            "title": "Send to Android",  
            "builder_id": 1,  
            "extras": { "newsid": 321 
            }  
          }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        },  
        "custom_args": { "business": "info" }  
      },  
      {  
        "target": "registration_id_2",  
        "platform": "ios",  
        "notification": {  
          "ios": {  
            "alert": "Hi, MTPush!",  
            "sound": "default",  
            "badge": "+1",  
            "extras": { "newsid": 321 
            }  
          }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        }  
      }  
    ]  
  }

此代码块在浮窗中显示

2. 通过 alias 批量推送

curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/alias \ -H "Content-Type: application/json" \ -u "AppKey:MasterSecret" \ -d '{ "requests": [ { "target": "user_alias_1", "platform": "all", "notification": { "android": { "alert": "Hi, Push!", "title": "Send to Android" }, "ios": { "alert": "Hi, MTPush!", "sound": "default" } }, "options": { "time_to_live": 60, "apns_production": false } }, { "target": "user_alias_2", "platform": "ios", "notification": { "ios": { "alert": "Hi, MTPush!", "sound": "default", "badge": "+1", "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/alias \  
  -H "Content-Type: application/json" \  
  -u "AppKey:MasterSecret" \  
  -d '{  
    "requests": [  
      {  
        "target": "user_alias_1",  
        "platform": "all",  
        "notification": {  
          "android": { "alert": "Hi, Push!", "title": "Send to Android" },  
          "ios": { "alert": "Hi, MTPush!", "sound": "default" }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        }  
      },  
      {  
        "target": "user_alias_2",  
        "platform": "ios",  
        "notification": {  
          "ios": {  
            "alert": "Hi, MTPush!",  
            "sound": "default",  
            "badge": "+1",  
            "extras": { "newsid": 321 }  
          }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        }  
      }  
    ]  
  }'

此代码块在浮窗中显示

请求参数

请求体结构：

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

              
              {  
  "requests": [  
    {  
      "target": "string",     // 必填，推送目标（registration_id 或 alias）  
      "platform": "string",   // 必填，推送平台（android/ios/all）  
      "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	推送平台：`android`、`ios` 或 `all`
`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
    }
  }
}

此代码块在浮窗中显示

成功响应（部分限流）

{ "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": "Rate limit exceeded for the API" } }, "170976fa8a9277c25d4": { "target": "170976fa8a9277c25d4", "success": false, "error": { "code": 23008, "message": "Rate limit exceeded for the API" } } } }

              
              {
    "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": "Rate limit exceeded for the API"
            }
        },
        "170976fa8a9277c25d4": {
            "target": "170976fa8a9277c25d4",
            "success": false,
            "error": {
                "code": 23008,
                "message": "Rate limit exceeded for the API"
            }
        }
    }
}

此代码块在浮窗中显示

失败响应（全局错误）

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

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

注意事项

限流处理： 发生限流时返回部分成功结果（已推送的 msg_id + 失败项的 error）。
重复检查： 同一批次内所有 target 和 cid 必须唯一。
数量限制： 单次请求不超过 500 个目标。
错误处理： 全局错误（如鉴权失败）会立即中断，不返回部分结果。