Login

Omnichannel

Security and Compliance

Substituting Event Data into Messages

Mobile app developers often need to send dynamic content messages to their users. For example, transactional messages initiated from the backend: order confirmation, delivery, etc.

Transactional message

We recommend using Generate event API method to send custom backend events to Yespo. For more information on sending orders data, please read the instructions.

Let's consider in practice how to substitute data from events to a message.

Note

The message with dynamic event content must participate in the workflow triggered by the corresponding event.

See the following instructions to learn how to launch a triggered campaign on event.

Event Data Types

An event can contain different data types, which are substituted differently in the message:

  • Simple data (strings and numbers not included in the object or array)
  • Object data 
  • Array data

Let's consider how to transfer these types of data to the message, using the following request as an example:

{
    "eventTypeKey": "data_for_message",
    "keyValue": "user@imaginary.email",
    "params":
    [
        {
            "name": "EmailAddress",
            "value": "user@imaginary.email"
        },
        {
            "name": "externalOrderId",
            "value": 20233
        },
        {
            "name": "sellerName",
            "value": "Shop Tea"
        },
        {
            "name": "object",
            "value":
            {
                "title": "Black Tea",
                "text": "Tea from the Tonganagaon plantation in India",
                "img": "https://pics.site.com/repository/home/1/common/images/1576074904732.jpg",
                "price": "$11.05",
   "link": "https://site.com"
            }
        },
        {
            "name": "array",
            "value":
            {
                "array_items":
                [
                    {
                        "title": "Black Tea",
                        "text": "Tea from the Tonganagaon plantation in India",
                        "img": "https://pics.site.com/repository/home/1/common/images/1576074904732.jpg",
                        "price": "$11.05"
                    },
                    {
                        "title": "Green Tea",
                        "text": "Tea from the Indian region of Darjeeling",
                        "img": "https://pics.site.com/repository/home/1/common/images/1576074904060.jpg",
                        "price": "$10.20"
                    },
                    {
                        "title": "Herbal tea",
                        "text": "Peach, rosehip, and apple, spring flavor.",
                        "img": "https://pics.site.com/repository/home/1/common/images/1576074902892.jpg",
                        "price": "$15.00"
                    }
                ]
            }
        }
    ]
}

Substituting simple data from event

We have "externalOrderId" and "sellerName"  fields with 20233 and "Shop Tea" values. These string and number are not included in the object or array.  

To substitute values to the message:

  • In the message template, use $data.get('externalOrderId') and $data.get('sellerName') velocity constructions, where externalOrderId and sellerName are field names from the request.

Substituting data from an event into a message

The user who initialized the event will receive the message:

Mobile push

Substituting object data from event

In the example, the object is the data of one product:

{
    "name": "object",
    "value":
    {
        "title": "Black Tea",
        "text": "Tea from the Tonganagaon plantation in India",
        "img": "https://pics.site.com/repository/home/1/common/images/1576074904732.jpg",
        "price": "$11.05",
        "link": "https://site.com"
    }
}

To access object data:

1. Select the message block in the workflow and specify the object name in the JSON field (in this request, ${object}).

Object name

2. In the message template, specify the velocity variables from the object in the appropriate fields:

  • $data.get('title')
  • $data.get('text')
  • $data.get('img')
  • $data.get('price')
  • $data.get('link')

Variables in email

The email will look like this:

Substitution of data in email

Sending a data object covers most needs for channels like SMS, Web Push, Mobile Push, Viber, and App Inbox.

To send more data, use an array.

Substituting array data from event

In the example, data about several products are transferred in the array:

{
    "name": "array",
    "value":
    {
        "array_items":
        [
            {
                "title": "Black Tea",
                "text": "Tea from the Tonganagaon plantation in India",
                "img": "https://pics.site.com/repository/home/1/common/images/1576074904732.jpg",
                "price": "$11.05"
            },
            {
                "title": "Green Tea",
                "text": "Tea from the Indian region of Darjeeling",
                "img": "https://pics.site.com/repository/home/1/common/images/1576074904060.jpg",
                "price": "$10.20"
            },
            {
                "title": "Herbal tea",
                "text": "Peach, rosehip, and apple, spring flavor.",
                "img": "https://pics.site.com/repository/home/1/common/images/1576074902892.jpg",
                "price": "$15.00"
            }
        ]
    }
}

To access array data:

1. Select the message block in the workflow and enter the array name in the JSON field (in our example it is ${array}).

Array name

2. In the email editor, highlight the appropriate strip, open the code, and add the velocity structure with the #foreach loop:

<!-- #foreach( $item in $data.get('array_items') ) -->
// html content
<!-- #end -->

Velocity code

The loop sequentially goes through the array elements, placing the data in the intermediate object $items (arbitrary name), which is used to substitute data into the message.

3. Specify the velocity variables from the array in the appropriate places of the temlate:

  • $item.get('title')
  • $item.get('text')
  • $item.get('img')
  • $item.get('price')
  • $item.get('link')

The email will look like this:

Data substitution

Note

The mobile push notification will be displayed differently on different devices, but we recommend writing at most 40 characters. That’s why it is not always rational to display the entire contents of the array using the foreach loop.

Instead, you can refer to a specific array element. Then velocity construction for the array will look like this: $!data.get('array_items').get(0).get(' name'), where the first element of the array is accessed (numbered from 0).

Any Questions?
We’re always happy to help!
Discount services
Schedule a Call
Fill in the form, and our specialists will call you back as soon as possible.
Discount services
Chat Support
We’re waiting for your questions!
Discount services
Email
Contact the support team