批量單推 API

功能說明

用於批量單推訊息，一次呼叫可對多個目標用戶進行推播。支援透過 registration_id 或 alias 推播：

透過 registration_id 推播： POST /v4/batch/push/regid
透過 alias 推播： POST /v4/batch/push/alias
能力限制：
- 單次請求最多支援 500 個推播目標
- 支援並行處理，提升效率
- 限流時回傳部分成功結果
- 本API和Push API共用QPS配額，使用本API推送 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	推播平台：`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 個目標。
錯誤處理： 全域錯誤（如驗證失敗）會立即中斷，不回傳部分結果。