Message extras

Extras (extras) carry additional information with a message and change how clients behave. They are stored as key-value pairs and are passed in the JSON body of a POST /message request (Content-Type: application/json).

Namespaces

Keys in .extras must have the following format: <top-namespace>::[<sub-namespace>::]<action>. Some namespaces are used by the official clients:

Namespace	Description
client::*	Reserved
client::display	Changes how the client displays the information
client::notification	Configures the notification
android::*	Reserved
android::action	Reacts to events
ios::*	Reserved
notifly::*	Service fields set by the server — do not set them yourself
All others	Defined by end users

client::display

contentType

Definition

contentType	description
text/markdown	Default; the message should be rendered as markdown. HTML must be ignored.
text/plain	The message is displayed as plain text. Links may be highlighted and clickable.

Note: Notifly renders messages as markdown by default. Markdown supports displaying images via ![](img url), and these images are loaded automatically when the message is viewed. For the same reason remote content is blocked by default in email clients, automatic loading of remote images can be used to collect information about the user.

Also, if part of a message is interpolated from a malicious external source, an attacker can inject malformed markdown that leads to information disclosure.

If a message is assembled from external sources (for example, script output), it is recommended to set text/plain explicitly — plain text does not interpret markdown and reduces possible security issues.

Example

{
  "extras": {
    "client::display": {
      "contentType": "text/plain"
    }
  }
}

Support

Client	description
Web admin	Uses GitHub Flavored Markdown
Notifly Android	Uses CommonMark

client::notification

click.url

click.url (string): opens the URL when the notification is tapped.

Example

{
  "extras": {
    "client::notification": {
      "click": {"url": "https://example.com/deploy/42"}
    }
  }
}

Support

Client	description
Notifly Android	Tapping the notification opens the URL instead of the message in the feed
Notifly iOS	Tapping the notification opens the URL in the embedded admin (beta)

bigImageUrl

bigImageUrl (string): shows a large image in the notification.

Example

{
  "extras": {
    "client::notification": {
      "bigImageUrl": "https://placekitten.com/400/300"
    }
  }
}

Support

Client	description
Notifly Android	You may need to expand the notification.

android::action

onReceive.intentUrl

onReceive.intentUrl (string): opens the URL right after the notification is delivered.

Example

{
  "extras": {
    "android::action": {
      "onReceive": {"intentUrl": "https://example.com/status"}
    }
  }
}

Support

Client	description
Notifly Android	By default a confirmation dialog is shown before opening (the “Confirm onReceive intents” setting). For silent messages (quiet hours, maintenance windows) the URL is not opened.

notifly::*

Fields prefixed with notifly:: are set by the server itself. Clients read them to display the message correctly; you do not need to send them in your requests.

Key	Meaning
notifly::ask	The message is an interactive question: type, options or form fields, status, answer deadline
notifly::delivery	A delivery hint. {"silent": true, "reason": "maintenance"} — the channel is in an active maintenance window: the message is shown in the feed, but silently and without alarm mode
notifly::screenshot	The key of a screenshot taken by a browser check on failure; clients show the image right in the feed
notifly::event, notifly::command, notifly::silent	Service frames (heartbeat status, commands to the client, etc.) — not shown as notifications; see WebSocket protocol