Skip to main content
POST
For pushes only your backend knows about, sent the moment something happens: a new chat message, a match, a reply. The push goes out during the request, usually within a second.
Use this for one-to-one messages that answer something a person did, never for marketing or re-engagement. Direct sends skip the holdout, quiet hours and caps, because they aren’t part of your notification program. Sending campaigns this way would hide them from the holdout, so you could no longer tell whether your program helps. Use a flow or a broadcast for those.

Authentication

Send a server key as a bearer token:
An ingest key (pna_...) is refused here, with the same 401 {"error": "unauthorized"} as a missing or revoked key. A server key can send pushes to any of your users: keep it on your server, never in your app.

Body

string
required
Your own id for the user, as you passed it to identify. At most 256 characters.
string
required
Your unique id for this push, at most 256 characters - for a chat push, the message’s id. Sending the same key again never sends a second push: you get back the result of the first. So you can retry a request that timed out without risking a duplicate.
string
required
At most 120 characters.
string
At most 120 characters.
string
required
At most 400 characters.
string
Opened when the push is tapped. At most 2048 characters.
number
The number to show on your app icon, such as the unread count. A whole number, 0 or more; 0 clears it. Leave it out to keep the current badge.
object
Custom keys for your app’s code, delivered beside the alert. Values may be any JSON. At most 20 keys; a key is letters, digits and underscores, and aps, pnai and deep_link are reserved. The whole push must fit in Apple’s 4 KB limit.

Response

string
Our id for the send. It’s the same for every retry with the same idempotency_key.
string
  • sent (200): Apple accepted the push.
  • pending (202): nothing has gone out yet, and we’ll retry on our side, so don’t send it again yourself. This happens when Apple is briefly unavailable.
  • cancelled (422): it won’t be sent. See reason.
string
When it was sent, as ISO 8601. Only when status is sent.
string
Why it was cancelled. Only when status is cancelled. For example:
  • message_too_large: the push is over Apple’s 4 KB limit.
  • all_tokens_unregistered: every device token was rejected by Apple, for example because the app was deleted.
  • delivery_unknown: we couldn’t tell whether Apple received it. It may have arrived, so it’s never retried.

Errors

Nothing is recorded for these errors, so you can retry with the same idempotency_key once the cause is fixed.