Sending messages

The Message Dispatch APIs permit an application to send specific messages, based on an experience definition to specific end users via a simple REST API call. The API call can include parameters which are substituted into the message to personalize the content or make the message contextually relevant. The resulting messages can be retrieved via the standard user message APIs and also can trigger push notifications to user devices.

Before dispatching any messages, the experiences that will be dispatched must be defined.

These experiences can be defined in the Control Room web management tool.

Sending messages with the dispatch API

Once an experience has been created, messages can be sent based on that experience with the message dispatch API, which works as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -X POST \
  'https://api.{region}.te2.io/v1/user-messages/venues/{venueId}/experience-type/EXTERNAL_{dispatchType}/dispatch' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "userIds": [
    "{userId}"
  ],
  "tokenReplacements": {
    "key1": "value1",
    "key2": "value2",
    ...
  }
}'

Parameters used here include:

• region: Your region. This is us or ap. If you are unsure which region you are in, contact your assigned Client Engagement Manager.

• venueId: The ID of the venue.
• dispatchType: The identifier used when creating the experience. Note that this string must be prefixed by EXTERNAL_, just the same as when creating or updating an experience.

The URL dispatchType parameter specifies the experience type which you wish to trigger, and the body provides a list of 1 or more user IDs to which you wish to send the message, as well as the values of any tokens which are to be used for parameter substitution in fields of the message. (See the section which follows).

A message can be sent to a single user or a set of users. Note that if a message is sent to multiple users, only one set of parameters can be provided to contextualize the message. Thus if the parameters are used for personalization (e.g. setting the user’s name in the message text), you will need to use a separate call for each user to accomplish that.

The generation of the message for the users and the delivery of push notifications, if configured, are asynchronous processes. After these processes have completed, the generated messages can be retrieved for the users. Information about these APIs can be found in the Retrieve user messages guide.

Support for parameter substitution

Many of the fields on the defined experience can use parameter substitution tokens within their definition. This is done by including the parameter in single curly brackets within the text of that field.

For example, given the parameters orderNumber and deliveryTime, a message body could include the text:

1
2
3
Thank you for your Order.  
Your Order Number is {orderNumber}.  You order will be delivered to your room at the
requested time of {deliveryTime}.

Parameter substitution is not restricted to only the body of the message. It is currently supported for all of the following fields:

• body
• link label
• link URL
• push message payload
• message title