Message formats | NAGRAVISION Documentation Portal

Overview

The format of the message that is received by a client 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": {
    "body": "<notification_body>",
    "title": "<notification_title>"
  },
  "data": { 
    "body": "<data_body>", 
    "title": "<data_title>",
    "referenceType": "{NOTIFICATION_UPDATE|ENTITLEMENT_UPDATE|EPG_UPDATE|EAS_UPDATE}" 
  }
}

The message is delivered as stringified JSON, and is shown here as regular JSON for readability.

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
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).

In some cases, if the message includes a notification section and is received while the client application is not open, the system shows the notification and the message never makes it to the client.

Message schema

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

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.

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 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		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`	The entitlement update reference		String
`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`						Allowed values: `OPEN_CONTENT` `OPEN_PRODUCT` – open a product (i.e., a promotion to purchase) `OPEN_APP` `OPEN_PACK`		Allowed values: `OPEN_CONTENT` `OPEN_PRODUCT` – open a product (i.e., a promotion to purchase) `OPEN_APP` `OPEN_PACK`		Allowed values: `OPEN_CONTENT` `OPEN_PRODUCT` – open a product (i.e., a promotion to purchase) `OPEN_APP` `OPEN_PACK`
`data.name`	The event name		String
`data.priority`	The priority of the message Except for EPG updates, 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`						String		String		String
`data.start`	The start date/time of the updated event		Date/time
`data.end`	The end date/time of the updated event		Date/time
`data.displayTime`	The amount of time that the message should be displayed on the screen Required if message is of `referenceType` `NOTIFICATION` or `PROMOTION` to indicate how long the message should remain on the screen.								Time in seconds		Time in seconds		Time in seconds
`data.body`	The message body				JSON – see Message format – entitlement changes		String – simple text message		Fields in `body` depend on the message type and action.		Fields in `body` depend on the message type and action.		Fields in `body` depend on the message type and action.
`data.body.productId`	The ID of the product to be opened if the user clicks on the message Required if `data.action` is `OPEN_PRODUCT`.								Product ID		Product ID		Product ID
`data.body.channelId`	The ID of the channel to be navigated to is the user clicks on the message Required 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 Required if `data.action` is `OPEN_CONTENT` and relates to VOD or 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 Required if `data.action` is `OPEN_CONTENT` and relates to a BTV event (instead of 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 Required 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 Required if `data.action` is `OPEN_PACK`.								Pack ID		Pack ID		Pack ID
`data.body.accountid`	The ID of the account for which entitlements are being update				Account ID
`data.body.deviceId`	The ID of the device for which entitlements are being update				Device ID
`data.body.status`	The status of the entitlement that has changed				String
`data.body.validFrom`	The date/time that the entitlement is valid from				Date/time
`data.body.expiryDate`	The date/time that the message is valid until				Date/time
`data.body.imageUrl`	The URL of an image to be displayed in the message window Optional – to be shown in 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 not in content catalogue.								URL		URL		URL

Overview

Client actions

Message schema

See also