Message format – general notifications, alerts, and promotions

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.

Message format

Mandatory fields

A message of this type always includes 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: a string containing a JSON object, which includes text (the message text) and can include other fields (see below). Parse it as JSON. If it doesn't parse, treat it as plain text.

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 on the message or on a CTA in the message. The target for the action is 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 is one of the following, and matches 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

Example

A promotional message targeted to a specific user profile, as received through AWS IoT Core:

{"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":"{\"text\":\"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 same message received through Firebase or ADM. The SDK delivers data as the key–value pairs below; the notification section is handled separately by the SDK:

{
  "referenceType": "PROMOTION",
  "userProfile": "Dave",
  "displayTime": "10",
  "title": "Movies We Know You'll Love",
  "action": "OPEN_PRODUCT",
  "body": "{\"text\":\"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\"}"
}

Either way, data.body contains the following JSON object once parsed:

{
  "text": "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"
}

See also

• Managing messaging

• Publish messages