批量單推 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配額，使用本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	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 個目標。
錯誤處理： 全域錯誤（如驗證失敗）會立即中斷，不回傳部分結果。