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

urgency

stringoptional

A hint for the push service and the device's battery saving. See urgency and TTL.

Rules: very-low, low, normal, high
Default: normal

ttl

integeroptional

How long the message may wait for an offline device. See urgency and TTL.

Rules: 0–2,419,200 seconds (28 days)
Default: 86400

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, urgency and ttl encoded as JSON, must be at most 3,000 bytes. Over that, the request fails with 400 VALIDATION_ERROR. The payload delivered to each browser adds two ids to it, attemptId and browserId.
Non-Latin scripts and emoji take more than one byte per character, so long text in them reaches the byte limit sooner.

Urgency and TTL#

urgency	Use it for
very-low	Things that can wait until the device is charging or on Wi-Fi.
low	Updates nobody has to see soon.
normal	Most notifications. This is the default.
high	Things that need attention now. Devices may wake up for it, so use it sparingly.

ttl is how many seconds the push service keeps the message while the device is offline. It counts from the moment Push accepted your request, so time spent in Push's queue is taken off.
ttl: 0 asks the push service to deliver now or drop the message. Push gives itself 300 seconds to hand it over; after that the attempt becomes expired.
An attempt that cannot be handed over before its TTL ends becomes expired.

Full example#

A body that uses every option:

⫻

request body

{  "recipient": "ops",  "title": "Disk usage above 90%",  "body": "db-1 is at 93%. Free space before the nightly backup.",  "url": "https://example.com/servers/db-1",  "icon": "https://example.com/icons/server.png",  "badge": "https://example.com/icons/badge.png",  "image": "https://example.com/graphs/db-1-disk.png",  "actions": [    {      "id": "open",      "title": "Open server",      "url": "https://example.com/servers/db-1"    },    {      "id": "ack",      "title": "Acknowledge",      "url": "https://example.com/alerts/812/ack"    }  ],  "tag": "disk-db-1",  "requireInteraction": true,  "silent": false,  "urgency": "high",  "ttl": 3600,  "data": {    "alertId": 812  }}

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, badge or image URLs. 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.