Send a notification
Queue a notification for a recipient's browsers, now or at a scheduled time.
/v1/notificationsAuthorization: Bearer sk_live_… or sk_test_…Creates a notification and one attempt per connected browser of the recipient, following its delivery policy, then answers before anything is sent. With sendAt or delay it is stored as scheduled and released later instead. See Sending notifications for the full walkthrough.
Request#
Headers#
- Rules
Bearer sk_live_…orBearer sk_test_…
- Rules
application/json
- Rules
- 1–255 characters
Body#
A JSON object of at most 16,384 bytes. Unknown fields are rejected. Every field except recipient, priority, urgency, ttl, sendAt and delay, encoded as JSON, must fit in 3,000 bytes, counted after priority defaults are added (size limits). Each field is explained in message options.
- Rules
^[a-z0-9][a-z0-9_-]{0,39}$
- Rules
- 1–120 characters
- Rules
- At most 480 characters
- Rules
- https URL with a domain name, at most 1,024 characters
- Rules
- https URL with a domain name, at most 512 characters
- Rules
- https URL with a domain name, at most 512 characters
- Rules
- https URL with a domain name, at most 512 characters
- Rules
- At most 2, with unique ids
actionClicked when the button is clicked.- Rules
^[a-z0-9][a-z0-9_-]{0,31}$
- Rules
- 1–40 characters
url opens.- Rules
- https URL with a domain name, at most 1,024 characters
- Rules
- 1–64 characters
- Default
false
- Default
false
urgent also sets requireInteraction: true and low sets silent: true unless you set them. Wins over urgency when both are sent. See Priority.- Rules
low,normal,highorurgent- Default
high
priority. Used only when priority is missing: very-low and low mean low, normal means normal, high means high.- Rules
very-low,low,normalorhigh
sendAt.- Rules
- 0–2,419,200 seconds
- Default
86,400
delay. See Scheduling.- Rules
- ISO 8601 with a time zone offset, 10 seconds to 3 days ahead
sendAt.- Rules
- 10–259,200 seconds
- Rules
- At most 1,024 bytes as JSON
Response#
A new notification is answered with 202 Accepted, whether it is sent now or scheduled. A repeated request with the same Idempotency-Key and the same body is answered with 200 OK and the original result, and nothing new is sent.
- Rules
- UUID
queued: the attempts were created and each one now gets its own status. scheduled: nothing is created or charged until sendAt.- Rules
queuedorscheduled
first delivery policy it is 1, and fallback attempts are added later. 0 for a scheduled notification.- Rules
- 0 or more
- Rules
liveortest
null when it was sent at once.- Rules
- ISO 8601, UTC
sk_test_… key the response looks the same, but nothing is sent and nothing is counted: each attempt is recorded as accepted straight away.A scheduled notification is answered like this:
⫻
202 Accepted
QUOTA_EXCEEDED is checked when the attempts are created. For a scheduled notification that is at release time: if the balance cannot cover it then, the notification is dropped instead of sent. See Scheduling.Errors#
| Code | HTTP | When |
|---|---|---|
| VALIDATION_ERROR | 400 | The body is not valid JSON, is over 16,384 bytes, breaks a field rule or has an unknown field; the notification is over 3,000 bytes; sendAt or delay is out of range, or both are sent; or Idempotency-Key is empty or longer than 255 characters. |
| UNAUTHORIZED | 401 | The Authorization header is missing, or the key is malformed, unknown or revoked. |
| QUOTA_EXCEEDED | 402 | The free monthly allowance is used up and the credit balance cannot cover this send. Nothing is sent or stored. Not returned for scheduled notifications, which are checked at release. |
| FORBIDDEN | 403 | A live key was sent from a browser: the request carries an Origin header. Call the API from your server, or use a test key. |
| PROJECT_SUSPENDED | 403 | The key's project is suspended. |
| IDEMPOTENCY_CONFLICT | 409 | The Idempotency-Key was already used with a different body. A concurrent request with the same key and body waits for the first and gets its replay instead. |
| INVALID_RECIPIENT | 422 | No recipient with that name exists in the key's project, or it has no connected browsers. Nothing is stored or charged. |
| RATE_LIMITED | 429 | The key, project or account went over its per-minute limit. Wait for Retry-After seconds. |
| INTERNAL_ERROR | 500 | Something failed on Push's side. Retry with the same Idempotency-Key. |
Example#
⫻
202 Accepted