Sending a message to an account or user profile | NAGRAVISION Documentation Portal

Request

You can send a message to a specific account or to a specific user profile. This sends the message to all the devices that belong to the account.

If the message is targeted to a specific user profile, it is up to the client application to deliver it only to the specified user profile.

If you use ION as your client application, note that it does not yet support user-profile-specific messages.

You may need to target a specific account for account-specific reasons, for example, an issue with a payment method or an upcoming subscription renewal.
You may want to target a specific user profile, for example, if you want to send a targeted promotion based on a profile’s known viewing habits.

To do this, send a POST request to:

Bash

http://<host>:<port>/messaging/v1/clients/{account_id}/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.

In this case, you may need to send the message twice – once with a notification and once without.

Headers

Content-Type: application/json

Mandatory fields

account_id (in URL) – the ID of the account
envelope object containing at least:
- from – who the notification is from
message – the message – a string or JSON converted to a string (that is, with line breaks removed and special characters escaped).
See Message format – general notifications for a detailed explanation of the expected message format.
Within message:
- data supports the following mandatory fields:
  - body – the body of the message displayed to the user
  - title – the title of the message displayed to the user
  - referenceType – one of:
    - NOTIFICATION – a general notification
    - ALERT – an alert
    - PROMOTION – a promotion

Optional fields

Within message:

notification block:
- Include a notification block if the notification is meant to be presented immediately to the user.
- Omit the notification block if the client should store the notification so that the user can view it when they choose to (for example, in an inbox).
data supports the following optional fields:
- userProfile – if the message is targeted to a specific user profile, this is the ID of the user profile
- body – the body of the message displayed to the user
  Within body, the following fields are supported:
  - action – the action to be performed when the user interacts with the message. One of:
    - OPEN_CONTENT
    - OPEN_PRODUCT
    - OPEN_APP
    - OPEN_PACK
  - One of the following. depending on the action:
    - If action is OPEN_CONTENT:
      - channelId specifies the channel to be switched to
      - contentId specifies the VOD content to be played
      - eventId specifies the live event to be played
    - If action is OPEN_PRODUCT, productId specifies the product to be displayed
    - If action is OPEN_APP, appUrl specifies the URL of the app to be opened
    - If action is OPEN_PACK, packId specifies the pack to be displayed
  - imageUrl – the URL of an image to be displayed in the message
  - videoUrl – the URL of a video to be displayed in the message
- title – the title of the message displayed to the user
- referenceType – one of:
  - NOTIFICATION – a general notification
  - ALERT – an alert
  - PROMOTION – a promotion
- priority – the priority of the message. The value and how it is 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).
- displayTime – the amount of time that the message should be displayed on the screen (in seconds)

Example

A request with this payload sends a message to the specified user profile:

JSON

{
  "envelope": {
    "from": "Operator"
  },
  "message": {
    "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",
      "title": "Movies We Know You'll Love",
      "body": {
        "Based on the movies you have watched, we think you will love this movie bundle! Click below to get it.": {
          "action": "OPEN_PRODUCT",
          "productId": "ACTION_MOVIE_BUNDLE",
          "imageUrl": "https://imageservice.sales.opentv.com/images/v1/image/Movie/GLOBAL_MV000336630000/Poster?width=300&aspect=2x3"
        }
      }
    }
  }
}

Note that "message" in the JSON above is shown with line breaks and is unescaped for clarity. In reality, you must stringify the JSON – remove all line breaks and escape all relevant characters within "message".

The JSON that you would actually use as the body of the request is: