Batch Single Push API
Batch Single Push API
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
= ApplicationAppKey
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 | Push platform: android , ios or all |
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
Successful response (partial rate limiting)
{
"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"
}
}
}
}
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
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 |
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: Returns partial success results during rate limiting (
msg_id
for succeeded +error
for failed). - Duplicate Check: All
target
orcid
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.