Sending a message to an account or user profile

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.

• 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:

http://<host>:<port>/messaging/v1/accounts/{accountId}/inbox

Headers

• Content-Type: application/json

Mandatory fields

• accountId (in URL) – the ID of the account

• envelope object containing at least:

  • from – who the notification is from (printable ASCII characters only)

• message – the message, as a string that contains JSON: on a single line, with special characters escaped. All values in data must be strings. See Message format – general notifications and the rules in Managing messaging.
  Within message, data must contain:

  • referenceType – one of:

    • NOTIFICATION – a general notification

    • ALERT – an alert

    • PROMOTION – a promotion

  • title – the title of the message displayed to the user

  • body – the body of the message: a string that contains a JSON object, with the message text in text and any of the additional fields listed below

Optional fields

The envelope object can also contain:

• id – a UUID that identifies the message. If you don't provide one, DMM generates it.

• expiration – the message time to live, in seconds

• event – an event type for tracking. It isn't delivered to the client application.

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 can also contain:

  • userProfile – if the message is targeted to a specific user profile, the ID of the user profile

  • action – the action to be performed when the user interacts with the message. One of OPEN_CONTENT, OPEN_PRODUCT, OPEN_APP, or OPEN_PACK.

  • 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, as a string (for example, "10")

• Within the JSON object in data.body:

  • Depending on data.action:

    • If action is OPEN_CONTENT: channelId specifies the channel to be switched to, contentId the VOD content to be played, or eventId 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

Example

A request with this payload sends a promotion to the specified user profile. Here, message and data.body are shown as JSON objects for clarity:

{
  "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",
      "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"
      }
    }
  }
}

In the actual request, message is a string, and data.body is a string inside it. This is the JSON that you would actually use as the body of the request:

{
  "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\",\"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\\\"}\"}}"
}

Response

• HTTP 200 – the message was sent to all the account's devices.

• HTTP 207 – the message was sent to some of the account's devices but not others. The response gives the number of devices and the IDs of the devices that succeeded and failed.

• HTTP 404 – no devices were found for the account.

• HTTP 500 – the request was not valid (for example, the message contains a line break) or the message could not be sent.

See also

For full details of this API, see the Device Messaging Manager (DMM) API documentation v1.