POST /api/push/send
Send a notification to every phone in a push group.
Body
| Field | Type | Instructions |
|---|---|---|
pushGroupId | string | Required. The group to send to. |
title | string | The bold first line. Send a title, a message, or both. |
subtitle | string | The line under the title. |
message | string | The body text. Send a title, a message, or both. |
imageUrl | string | A picture shown with the notification. WebP, PNG, or JPEG. |
actionURL | string | The page a tap opens. Must start with http:// or https://. Without it, a tap opens the group in the app. |
name | string | A label for this message in the dashboard log. Phones never see it. |
Example
1 2 3 4 5 6 7 8 9 10 11 12
curl -X POST https://api.webliveactivity.com/api/push/send \ -H 'Content-Type: application/json' \ -H 'x-api-key: wla_your_key' \ -d '{ "pushGroupId": "acme-orders", "title": "Your order shipped!", "subtitle": "Order #1234", "message": "Your package is on the way. Expected delivery: tomorrow by 5 PM.", "imageUrl": "https://acme.example/shipped.webp", "actionURL": "https://acme.example/orders/1234", "name": "Shipping notice" }'
Response
targeted is how many phones the notification was sent to. It is 0 when no one has joined, and then nothing is billed.
1 2 3 4 5 6
{ "ok": true, "targeted": 42, "groupId": "pg-7hk3mzq2wd9x", "pushGroupId": "acme-orders" }
Delivery
- Sends go out right away. They are not combined like Live Activity updates: two sends are two notifications.
- Every notification alerts the phone. There is no quiet send.
- A phone that is off gets it when it comes back, up to 3 days later. iPhone keeps only the newest one.
- Each phone that receives it counts as one push. See delivery and billing.
Errors
| Status | Meaning |
|---|---|
| 400 | No pushGroupId, no title or message, or an actionURL that is not http or https. |
| 402 | FREE_TIER_LIMIT_REACHED: the Free plan's monthly pushes are used up. Only when someone has joined. |
| 413 | The notification is over 4KB. Shorten the text. |
All other errors are in errors and limits.
