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.

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.

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.

The user who initialized the event will receive the message:

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}).

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')

The email will look like this:

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}).

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

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: