Message format

Overview

An operator can send general notifications, alerts, and promotions to client devices using one of the DMM APIs or using Operator Console (OpCon).

This page explains the format of these messages and how a client application should handle them.

Mandatory fields

A message of this type will always include the following fields:

data.referenceType – the type of message. One of NOTIFICATION, ALERT, or PROMOTION.
data.title – the message title
data.body – the message body. This must include text, but can also include other fields (see below).

Optional fields

A message of this type can also include the following optional fields:

notification – a notification to be presented to the user immediately, containing a title and body:
- If a notification block is present, the client should present the notification to the user immediately.
- If there is no notification block, the client should store the notification so that the user can view it when they choose to (for example, in an inbox).
data.userProfile – if present, the message should be shown only to the specified user profile and not to any of the other user profiles.
If the specified user profile is not the one currently in use, the client should save the message and make it available to the target user profile when it is next used.
data.priority – the priority of the message. The possible 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).
data.displayTime – the time the message should be displayed for (in seconds)
data.action – the action to be performed if the user clicks/taps in the message or on a CTA in the message. The target for the action is specified in data.body (see below). data.action can be one of:
- OPEN_CONTENT
- OPEN_PRODUCT
- OPEN_APP
- OPEN_PACK
data.body.<target> – the target that the app should take the user to if they click/tap on the message or on a CTA in the message. It can be one of the following, and must match the value of data.action:
- If action is OPEN_CONTENT:
  - channelId is the ID of the channel to be switched to.
  - contentId is the ID of the content to be played.
  - eventId is the ID of the event to be switched to.
- If action is OPEN_PRODUCT, productId is the ID of the product to be opened (to allow the user to purchase / subscribe to the product).
- If action is OPEN_APP, appUrl is the URL of the app to be opened.
- If action is OPEN_PACK, packId is the ID of the pack to be opened (to allow the user to purchase / subscribe to the pack).
data.body.imageUrl – the URL of an image to be displayed in the message
data.body.videoUrl – the URL of a video to be displayed in the message

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.

Example

Example payload of a promotional message targeted to a specific user profile:

JSON

{
  "notification": {
    "title": "Movies We Know You'll Love",
    "body": "Based on the movies you have watched, we think you will love this movie bundle!"
  },
  "data": {
    "referenceType": "PROMOTION",
    "userProfile": "Dave",
    "displayTime": 10,
    "title": "Movies We Know You'll Love",
    "action": "OPEN_PRODUCT",
    "body": {
      "Based on the movies you have watched, we think you will love this movie bundle! Click below to get it.": {
        "productId": "ACTION_MOVIE_BUNDLE",
        "imageUrl": "https://imageservice.sales.opentv.com/images/v1/image/Movie/GLOBAL_MV000336630000/Poster?width=300&aspect=2x3"
      }
    }
  }
}

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

When delivered to the client, the above example JSON will be stringified as follows: