Message options
Every field a notification accepts, with its limits and defaults.
These are the fields of the POST /v1/notifications body. Lengths count characters (UTF-16 code units) unless they say bytes. Every URL must use https and a domain name; IP addresses are rejected.
Fields#
recipient
stringrequired
The name of a recipient in the API key's project. See Recipients.
- Rules
- 1–40 characters,
^[a-z0-9][a-z0-9_-]{0,39}$
title
stringrequired
The bold first line of the notification.
- Rules
- 1–120 characters
body
stringoptional
The text under the title. Systems may cut long text when they show it.
- Rules
- Up to 480 characters
url
stringoptional
Opened when the person clicks the notification. Without it, a click closes the notification and is still recorded.
- Rules
- https, up to 1,024 characters
icon
stringoptional
A small image next to the text. When omitted, the system shows its default.
- Rules
- https, up to 512 characters
badge
stringoptional
A small monochrome icon, used mainly in the Android status bar.
- Rules
- https, up to 512 characters
image
stringoptional
A large picture inside the notification, on systems that show one.
- Rules
- https, up to 512 characters
actions
object[]optional
Buttons on the notification. Each has an
id (1–32 characters, ^[a-z0-9][a-z0-9_-]{0,31}$), a title (1–40 characters) and an optional https url (up to 1,024 characters). See Actions and click tracking.- Rules
- Up to 2, unique ids
tag
stringoptional
A notification with the same tag replaces the one on screen instead of stacking. Push also sends it as the Web Push
Topic, so an older message still waiting at the push service is replaced too. A tag that is not 1–32 of A-Z a-z 0-9 _ - is hashed into a valid topic.- Rules
- 1–64 characters
requireInteraction
booleanoptional
Keep the notification on screen until the person acts on it, where the system supports it.
- Default
false
silent
booleanoptional
Show the notification without sound or vibration.
- Default
false
priority
stringoptional
How much the notification matters. It sets the Web Push urgency, makes
low silent and urgent stay on screen. See Priority.- Rules
low,normal,high,urgent- Default
high
urgency
stringoptional
Deprecated alias of
priority: very-low and low become low. Ignored when priority is sent. See the urgency field.- Rules
very-low,low,normal,high
ttl
integeroptional
How long the message may wait for an offline device. See TTL.
- Rules
- 0–2,419,200 seconds (28 days)
- Default
86400
sendAt
stringoptional
Send later, at this time. Not together with
delay. See Scheduling.- Rules
- ISO 8601 with a zone, 10 seconds to 3 days ahead
delay
integeroptional
Send later, this many seconds from now. Not together with
sendAt. See Scheduling.- Rules
- 10–259,200 seconds
data
objectoptional
Your own JSON object. It is never shown; Push's service worker keeps it on the notification as
notification.data.data.- Rules
- Up to 1,024 bytes as JSON
Size limits#
- The whole request body may be at most 16,384 bytes.
- The message, meaning every field except
recipient,priority,urgency,ttl,sendAtanddelayencoded as JSON, must be at most 3,000 bytes. It is measured after priority fills insilentorrequireInteraction. Over that, the request fails with400 VALIDATION_ERROR. The payload delivered to each browser adds two ids to it,attemptIdandbrowserId. - Non-Latin scripts and emoji take more than one byte per character, so long text in them reaches the byte limit sooner.
TTL#
ttlis how many seconds the push service keeps the message while the device is offline. It counts from the moment Push accepted your request, or from the release time of a scheduled notification, so time spent in Push's queue is taken off. It also bounds how long Push keeps retrying.ttl: 0asks the push service to deliver now or drop the message. Push gives itself 300 seconds to hand it over; after that the attempt becomesexpired.- An attempt that cannot be handed over before its TTL ends becomes
expired.
Full example#
A body that uses every option:
⫻
request body
How it looks#
- The browser and operating system decide how the notification looks. Images, badges and buttons are not shown everywhere; see Browser compatibility.
- Push never downloads your
icon,badgeorimageURLs. The person's browser fetches them when it shows the notification, so host them somewhere public and fast.
NoteNotifications can show on lock screens. Never put passwords, codes or other secrets in them.