Batch Single Push API | WebPush Developer Guide REST API

The examples use Singapore. Select the Base URL for your application’s data center before making requests. For group push, use the group’s data center and credentials. See the address list in REST API Overview.

Function Description

Used for batch single push notifications, allowing multiple target users to receive pushes in one call. Supports pushing via registration_id or alias:

Push via registration_id: POST /v4/batch/push/regid
Push via alias: POST /v4/batch/push/alias
Capability Limits:
- Maximum 500 push targets per request
- Supports concurrent processing for efficiency
- Returns partial success results during rate limiting
- This API and the Push API share the same QPS quota. Using the batch push API to push 1 regid or 1 alias consumes 1 QPS quota of the Push API.

Authentication

Add authentication field in HTTP Header:

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

This code block in the floating window

Generation method: base64(username:password)
- username = Application AppKey
- password = Master Secret
Access path: Console → Application Settings → Application Info

Endpoints

Batch push via registration_id

POST /v4/batch/push/regid

              
              POST /v4/batch/push/regid

This code block in the floating window

Batch push via alias

POST /v4/batch/push/alias

              
              POST /v4/batch/push/alias

This code block in the floating window

Request Examples

1. Batch push via 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
        }
      }
    ]
  }'

This code block in the floating window

2. Batch push via 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
        }
      }
    ]
  }'

This code block in the floating window

Request Parameters

Request body structure:

{ "requests": [ { "target": "string", // Required, push target (registration_id or alias) "platform": "string", // Required, push platform settings (refer to Push API) "notification": "object", // Optional, notification content (refer to Push API) "message": "object", // Optional, custom message (refer to Push API), cannot coexist with notification "options": "object", // Optional, push options (refer to Push API) "custom_args": "object" // Optional, parameters passed to client } ] }

              
              {  
  "requests": [  
    {  
      "target": "string",     // Required, push target (registration_id or alias)  
      "platform": "string",   // Required, push platform settings (refer to Push API)
      "notification": "object",  // Optional, notification content (refer to Push API)  
      "message": "object",     // Optional, custom message (refer to Push API), cannot coexist with notification  
      "options": "object",     // Optional, push options (refer to Push API)  
      "custom_args": "object"  // Optional, parameters passed to client  
    }  
  ]  
}

This code block in the floating window

Parameter descriptions:

Field	Required	Type	Description
`requests`	Yes	array	Batch request array (max 500 items, `target` must be unique per batch)
`target`	Yes	string	Target value: - `/regid` endpoint: `registration_id` - `/alias` endpoint: `alias`
`platform`	Yes	string	For WebPush, use `web` or `all`; `all` represents the Web platform for a WebPush application.
`notification`	No	object	Notification content (same structure as Push API)
`message`	No	object	Custom message (same structure as Push API)
`options`	No	object	Push options (e.g. `time_to_live`, `apns_production`)
`custom_args`	No	object	Custom passthrough parameters

Response Examples

Successful response (all succeeded)

{ "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
    }
  }
}

This code block in the floating window

HTTP 200 response (item-level rate limiting)

This example shows some targets exceeding the available quota after batch processing begins. The outer HTTP status is 200; it does not mean that every target succeeded.

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

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

This code block in the floating window

{ "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
        }
    }
}

This code block in the floating window

Failed response (global error)

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

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

This code block in the floating window

Failed response (parameter error)

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

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

This code block in the floating window

Error Code Reference

Unless otherwise noted, the HTTP statuses below apply to request-level errors. Item-level errors are returned in results[target].error, while the outer HTTP status remains 200.

Error Code	Description	Resolution	HTTP Status
Global Error Codes
21004	Basic authentication failed	Check AppKey/MasterSecret	401
21008	AppKey length is not 24 characters	Verify AppKey format	400
21038	No push permission for the app	Check app configuration	400
21043	No push permission (pending payment)	Resolve billing issue	400
23009	IP not in allowlist	Add server IP to allowlist	400
21009	Internal system error (do not retry)	Contact technical support	400
Rate Limit Errors
23008	API rate limit reached	Retry failed items if partial success	400 (request level); 200 (item results)
Parameter Errors
21003	Invalid parameter value	Check request body format	400
21015	Invalid request parameters	Validate required fields	400
21016	Parameter validation failed	Check field types and value ranges	400

Full error codes: Create Push API - Response

Notes

Rate Limit Handling: Rate limiting of the entire request returns HTTP 400. After batch processing begins, item-level rate limits return success=false and error.code=23008 in results with HTTP 200. Retry only failed items.
Duplicate Check: All targetor cid values must be unique within a batch.
Quantity Limit: Maximum 500 targets per request.
Error Handling: Global errors (e.g. auth failure) immediately terminate without partial results.