Message formats | NAGRAVISION Documentation Portal

Overview

The format of the message that a client receives, and how the client is expected to handle it, depend on the type of message.

In general, all messages share the same top-level format:

JSON

{
  "notification": {
    "title": "<notification_title>",
    "body": "<notification_body>"
  },
  "data": {
    "referenceType": "<NOTIFICATION_UPDATE|NOTIFICATION|ALERT|PROMOTION|ENTITLEMENT_UPDATE|EPG_UPDATE|EAS_UPDATE>",
    "title": "<data_title>",
    "body": "<data_body>"
  }
}

The notification section is optional. The fields in data depend on the type of message.

How the message arrives

How the client receives a message depends on the messaging service the device uses:

Service	Devices	What the client receives
Firebase Cloud Messaging (FCM)	iOS and Android	The Firebase SDK delivers `data` as a set of key–value pairs in which every value is a string. Firebase also adds fields of its own (such as a message ID and the sender). These vary between platforms and SDK versions, so don't rely on them.
Amazon Device Messaging (ADM)	Fire TV	The ADM SDK delivers `data` as a set of key–value pairs in which every value is a string.
AWS IoT Core	Tizen and webOS Smart TVs	The message payload is the message JSON as text, exactly as it was sent. Parse it to read `notification` and `data`. Values keep their JSON types.

So, whichever service a message comes through:

Read values as strings. A value that is a number in one service's message (for example, the start and end times in an EPG update) can arrive as a string through another. Accept both.
Parse data.body as JSON. In NOTIFICATION, ALERT, and PROMOTION messages, data.body is a string that contains a JSON object. Parse it to read the data.body.<field> fields listed below. If it doesn't parse as JSON, treat it as plain text. (In NOTIFICATION_UPDATE messages, data.body is always plain text.)
Rely only on notification and data. Ignore any other fields added by the messaging service.

Client actions

The client should:

Check the value of data.referenceType and act accordingly. See the following pages for each type:
- NOTIFICATION_UPDATE – Message format – general notifications
- EAS_UPDATE – Message format – Emergency Alert System (EAS)
- ENTITLEMENT_UPDATE – Message format – entitlement changes
- EPG_UPDATE – Message format – EPG update
- NOTIFICATION, ALERT, or PROMOTION – Message format – general notifications, alerts, and promotions
EPG changes can also arrive in a format that has no data.referenceType – see Respond to metadata change notifications.
Check for the presence of a notification section:
- If it is present, the client should immediately display the notification to the user, using the specified title and body.
- If there is no notification section, the client should store the notification so that the user can view it when they choose to (for example, in an inbox).

On devices that use Firebase (iOS and Android), if a message includes a notification section and arrives while the client application is in the background or not running, the operating system displays the notification itself. The client application receives the data section only if the user taps the notification. If the user dismisses it, the application never receives the message.

Message schema

EAS updates are not listed here – see Message format – Emergency Alert System (EAS).

Operators can send messages with the following fields. EPG update, entitlement, and EAS messages are generated by the platform and have fixed formats – see their pages, listed above.

Although any fields can be used in the data section, NAGRAVISION recommends that the following fields be used.

Note that these fields rely on the client application being updated to make use of them.

If you use ION as your client application, it does not yet recognise these fields.

Fields named data.body.<field> are inside the JSON object that data.body contains.

Field name	Description	EPG update		Entitlement		Notification (general/OpCon)		Notification		Alert		Promotion
Field name	Description	Valid in context	Value	Valid in context	Value	Valid in context	Value	Valid in context	Value	Valid in context	Value	Valid in context	Value
`data.referenceType`	Tells the client what type of message this is		`EPG_UPDATE`		`ENTITLEMENT_UPDATE`		`NOTIFICATION_UPDATE`		`NOTIFICATION`		`ALERT` (Requires clearing by the user.)		`PROMOTION`
`data.userProfile`	Specifies the user profile that the message is intended for. The client should only show the message to the specified user profile. If a different user profile is in use, the client should save the message and show it when the target user profile is next used.								User profile ID		User profile ID		User profile ID
`data.title`	The message title						String		String Title, short description		String Title, short description		String Title, short description
`data.message`	The message contents								String (optional)		String (optional)		String (optional)
`data.reference`	What the message refers to: the channel (EPG update) or the account (entitlement)		Channel ID		Account ID
`data.action`	The action associated with the message. If this field has a value, the client must provide a way for the user to trigger the action.		`REFRESH`		`REFRESH`				One of: `OPEN_CONTENT` `OPEN_PRODUCT` – open a product (that is, a promotion to purchase) `OPEN_APP` `OPEN_PACK`		One of: `OPEN_CONTENT` `OPEN_PRODUCT` – open a product (that is, a promotion to purchase) `OPEN_APP` `OPEN_PACK`		One of: `OPEN_CONTENT` `OPEN_PRODUCT` – open a product (that is, a promotion to purchase) `OPEN_APP` `OPEN_PACK`
`data.name`	The name of the change		`epg` (schedule change) or `content` (metadata change)		`Entitlement change in account`
`data.priority`	The priority of the message. For EPG updates it is always `HIGH`. For entitlement changes it is `NONE`, `LOW`, or `HIGH`. For other messages, the values and how they are used are determined by the operator. For example, the client could use this to decide when to show the message (for example, immediately or only once the user finishes watching the current content).		`HIGH`		`NONE`, `LOW`, or `HIGH`				String		String		String
`data.start`	The start of the time window that changed		Unix time (seconds)
`data.end`	The end of the time window that changed		Unix time (seconds)
`data.deviceId`	The ID of the device that the entitlement is for				Device ID, or `"null"` if the entitlement is not for a specific device
`data.productid`	The ID of the product whose entitlement has changed. Note the lowercase `id`.				Product ID
`data.productType`	The type of product				One of `TRANSACTIONAL`, `SUBSCRIPTION`, `FREE`, `CAPABILITY`, `PPV`, `THIRDPARTY`, or `PACK`
`data.status`	The status of the entitlement				Currently always `"null"` – don't rely on it
`data.validFrom`	The date/time that the entitlement is valid from				Date/time, for example `Tue Aug 12 00:00:00 UTC 2025`
`data.expiryDate`	The date/time that the entitlement expires				Date/time, or `"null"` if there is no expiry date
`data.displayTime`	The amount of time that the message should be displayed on the screen. Always present in `NOTIFICATION` and `PROMOTION` messages.								Time in seconds		Time in seconds		Time in seconds
`data.body`	The message body						String – simple text message		String containing a JSON object. Its fields depend on the message type and action – see the `data.body.<field>` rows below.		String containing a JSON object. Its fields depend on the message type and action – see the `data.body.<field>` rows below.		String containing a JSON object. Its fields depend on the message type and action – see the `data.body.<field>` rows below.
`data.body.text`	The message text (proposed)								String		String		String
`data.body.productId`	The ID of the product to be opened if the user clicks on the message. Present if `data.action` is `OPEN_PRODUCT`.								Product ID		Product ID		Product ID
`data.body.channelId`	The ID of the channel to be navigated to if the user clicks on the message. Present if `data.action` is `OPEN_CONTENT` and relates to a channel.								Channel ID		Channel ID		Channel ID
`data.body.contentId`	The ID of the content to be opened if the user clicks on the message. Present if `data.action` is `OPEN_CONTENT` and relates to VOD or an event (editorial ID).								Content ID		Content ID		Content ID
`data.body.eventId`	The ID of the event to be opened if the user clicks on the message. Present if `data.action` is `OPEN_CONTENT` and relates to a BTV event (instead of a content ID).								Event ID		Event ID		Event ID
`data.body.appUrl`	The URL of the app to be opened if the user clicks on the message. Present if `data.action` is `OPEN_APP`.								App URL		App URL		App URL
`data.body.packId`	The ID of the pack product to be opened if the user clicks on the message. Present if `data.action` is `OPEN_PACK`.								Pack ID		Pack ID		Pack ID
`data.body.imageUrl`	The URL of an image to be displayed in the message window. Optional – to be shown in the message window if provided.								URL		URL		URL
`data.body.videoUrl`	The URL of a video to be displayed in the message window. Optional – expected to be a playable video that is not in the content catalogue.								URL		URL		URL

Overview

How the message arrives

Client actions

Message schema

See also