Last updated: 23 February 2022

To better understand the power of templating and dynamic messages, let’s work our way through two simple use cases.

Data

Dynamic content gets populated from APIs and/or spreadsheets. For these examples, we will work with a free API: https://reqres.in

Because it’s free and public, it’s easy for you to go along and follow the instructions. By the end of these tutorials, you’ll have enough knowledge to apply these to any API you might actually need to use.

To set you up, go to Integrations. Click Add new.

Give your integration a name (e.g. Reqres).

For the base URL is https://reqres.in/api

This API doesn’t require any authorization.

There are no headers needed. Hit Save.

We will create a simple GET endpoint, which will allow us to retrieve the information from the API:

Understand the data structure

Before we build anything, let’s double check the structure of the data we will receive from our API.

We can see in Reqres data is formatted like this:

"data": [
    {
        "id": 7,
        "email": "michael.lawson@reqres.in",
        "first_name": "Michael",
        "last_name": "Lawson",
        "avatar": "https://reqres.in/img/faces/7-image.jpg"
    },
    ...
]
CODE

 So, to access a user’s email address, we will need to enter data.email. To access their first name, data.first_name. And so on.

This information will come in handy when we start building.

Right! We’re ready to move ahead with our examples.

Example #1 - Dynamic carousel (for statement)

For our first scenario, we’re going to dynamically create a carousel. Using our API, we’ll populate a carousel with

  • The name of each user as title

  • Their name as subtitle

  • Their picture as the image

  • A link to a website as the image link (we’ll using http://google.com)

  • A link button to ‘read more’, sending them to http://google.com too

Building this manually would be a time-consuming process, particularly since we don’t actually know how many users there are in this database.

With templating, we can do this in just a few lines.

Create the conversation

Go to the Builder.

Create a new conversation. Give it a name, a description, and a simple trigger (e.g. message equals users).

Create the message

Edit the first message by clicking the three dots then Edit response.

Under message type, select Dynamic.

Delete everything from the message (aside from the opening and closing square brackets), we’ll start from scratch.

Ensure your cursor is in the middle of the square brackets and then, under Add response, select Carousel.

Learn about the carousel template and its associated values

Using what we know of the data structure, we can build the following template:

[
    {
        "type": "carousel",
        "content": {
            "items": [
                {% for user in integration.data.data %}
		            {% if loop.index < 10 %}
        	            {
         		            "title": "{{user.first_name}} {{user.last_name}}",
         			        "subtitle": "{{user.first_name}} {{user.last_name}}",
         			        "image": "{{user.avatar}}",
          			        "image_description": "{{user.first_name}} {{user.last_name}}",
         			        "url": "https://google.com",
          			        "responses": [
            			        {"type": "url", "label": "Read more", "action": "https://google.com"}
          			        ]
        		        }{% if not loop.last and loop.index != 9 %},{% endif %}
			        {% endif %}
                {% endfor %}
            ]
        }
    }
]
CODE

Understand the template

The structure of the template is simple. 

First, we define its type; carousel.

Then, we set up the for loop. In this example, we want to create a carousel card for every user. So, we will need to loop over the data every time we create a new item.

What if we wanted to create an entirely new carousel message for every user? We would set up the for loop at the very beginning of the template, turning it into an entire array.

Finally, we enter the values for each field.

Set up the integration

Now that we have the template all written out, we need to tell our chatbot platform where to fetch this data. We already have an integration set up, so we just need to tie the two together.

Click Advanced Settings. Under Data type, select API request response. Find your integration and endpoint, and hit Save.

Test the template

All done! Go to Demo and test your conversation. If you’ve followed this process with us and used the Reqres API, you should have a carousel with six items.

Use cases that follow the same approach:

  • Creating a carousel that displays available products in stock from an API.

  • Creating a standard message that displays a comma separated list of names of all participants to a competition, pulled from a spreadsheet.

Example #2 - Dynamic standard message (if statement)

We’re going to change gears a little bit with this one and use an if statement.

For this scenario, we’re going to dynamically create an action message for every person on our database whose first name is Rachel. 

If their name is Rachel, we’ll send an action message with a button to send Rachel an email. If their name is not Rachel, we’ll ignore them.

Because you’ve had a peek at the API on Reqres, you already know there’s only one Rachel – therefore in this case this template will only produce one response. However, the same process applies if there were 17 Rachels in our database. Our template would create an action message per Rachel.

Create the conversation

Go to the Builder.

Create a new conversation. Give it a name, a description, and a simple trigger (e.g. message equals rachel).

Create the message

Edit the first message by clicking the three dots then Edit response.

Under message type, select Dynamic.

Delete everything (aside from the opening and closing square brackets) from the message, we’ll start from scratch.

Ensure your cursor is inside the square brackets and click </> If tag to add the template statement.

Learn about the standard template and its associated values.

Using what we know of the data structure, we can build the following template:

[
    {% for user in integrations.data.data %}
        {% if user.first_name == 'Rachel' %}
            {
                "type": "action",
                "content": {
                    "text": "",
                    "responses": [
                        {"type":"mailto","label":"Email {{user.first_name}}","action":"{{user.email}}"}
                    ]
                }
            }
        {% else %}
           {
               "type": "standard",
               "content": {
                   "text": "This user is called {{user.first_name}}, not Rachel!"
               }
            }
        {% endif %}
    {% endfor %}
]
CODE

Understand the template

Because we want to create a new message per Rachel, we’re adding the IF tag at the very top of the template.

In the pass section, we create our Action message.

In the fail section, we create a Standard message. This will be sent for every user returned who does not have the first name, Rachel.

Set up the integration

Now that we have the template all written out, we need to tell our chatbot platform where to fetch this data. We already have an integration set up, so we just need to tie the two together.

Click Advanced Settings. Under Data type, select API request response. Find your integration and endpoint, and hit Save.

Test the template

And you’re done. If you go and test your template, you’ll see it will return the one-and-only Rachel Howell.

Use cases that follow the same approach:

  • If an item is in stock, send an action message with a purchase button. If not, let the users know it is out of stock with a standard message.

  • If you have a case study for one of your services, send a general message with a nice illustration, a summary of the case study, and a button to read it. If not, send a simple action message with a button to get in touch.