A carousel is a great way to show a list of options to your visitors in a visually attractive and convenient form. A carousel vignette can have a large image, a title, a description, and links. Visitors can scroll between your vignettes horizontally, click on links and explore the related web pages.
Use it to show a list of products or services, a list of articles, or any other list of items that fit your bot scenario. If you have an API connection configured, you can create dynamic carousels based on data in your API.
1. Add a carousel to your bot scenario
To add a carousel to your bot scenario, first, create a rich message card. Then you can add a carousel by clicking on the icon “vignette or carousel”.
To know more about the set-up of a bot scenario have a look at Set up a bot scenario.
2. Configuration of a carousel
Once you choose the rich card within the scenario, you have to choose the carousel icon to go into the configuration of the carousel.
You have the possibility to create a static carousel that has to be updated manually from time to time if your references are changing or a dynamic carousel that would be connected to your API and will be updated automatically by the API.
For each Vignette, you can choose an Image, Title & Description and Links.
Ideally, your image should be square and measure 285x285 px (if larger, it will be resized to fit).
2.1 Static Carousel
Within the configuration of the carousel you can at any time do the following actions:
- Add, edit and delete the image, title & description and links individually for each vignette
- Upload an image from your desktop or point to a URL
- Preview the carousel in action
2.2 Dynamic Carousel
Pre-requisite:
to have an API connection configured and an API connection card configured in a previous step of the scenario otherwise the dynamic carousel will not know which variables to use from all the API connections you might have.
To know more about API connection and its use within the dynamic carousel please refer to point 3 "Dynamic Carousel with an API connection".
For dynamic carousels, you can configure an image, title, description and links from your API or if you don’t want to use this information from your API, the fields can be filled up with static content.
In the same way, as for static carousels, you can handle the following actions within the carousel builder for dynamic carousels:
- Configure the number of vignettes for the carousel. In that case, the order of the vignettes is determined by the order the API sends the data.
- Preview the carousel in action
Good to know
- You can create up to 10 vignettes for the Dynamic Carousel (and 6 vignettes for the Static Carousel)
- You can have up to 5 links per vignette
- Only links are mandatory. Everything else is optional
- Keep your vignettes of equal height by adding the same elements to each vignette. For example, if at least one vignette has an image then make sure all of them have an image
3. Dynamic Carousel with an API connection
Dynamic carousels with an API connection allow you to show lists of elements in a beautiful way inside a chat. Use it to show products, services or content that is always updated with your data and personalised to your visitors.
In the following example, we are going to build a dynamic carousel that will show 5 products based on a question asked to a visitor.
3.1 Creation of an API connection
3.1.1 Creation of an API connection
Fill out the fields of your API connection as any other connection you might have done in the past. Learn more about how to configure an API connection.
To leverage the API connection with the dynamic carousel you will need to bind API connection variables to ArrayList of strings. This needs a specific JSONPath syntax that we will explain in the next section.
3.1.2 Mapping of the JSONPath for a dynamic carousel
1. Test your connection by clicking the “Test Connection” button, at the bottom of the screen, to visualise the JSONPath that is returned by your API. In our example the JSONPath looks like this, as expected it contains a JSON array in the “search_results” field:
{
"search_results": [
{
"title": "sixthreezero Around The Block Women's Beach Cruiser Bike",
"link": "https://www.smart-store.com/sixthreezero_around_the_block",
"image": "https://www.smart-store.com/images/sixthreezero_around_the_block.jpg",
"rating": 4.5,
"ratings_total": 4485,
"price": {
"raw": "$269.99"
}
},
{
"title": "BESPORTBLE Mountain Bike",
"link": "https://www.smart-store.com/besportble_mountain_bike",
"image": "https://www.smart-store.com/images/besportble_mountain_bike.jpg",
"rating": 3.6,
"ratings_total": 16,
"price": {
"raw": "$179.99"
}
},
.
.
. Rest of the list
.
.
]
}
2. Spot in the variables of your JSONPath which variables you will need for your carousel. In our example, it’s “title”, “link”, “image” and “price”.
3. In the “output variable” column, give a corresponding name to each of the variables above and write them down, one per line. In our example, we chose the names: product_title, product_link, product_image, and product_price. These can be anything you want and they are the variable names that you will later use to configure your dynamic carousel.
4. Use JSONPath syntax to map each “output variable” to a valid JSON item. In our example, the syntax looks like in the screenshot below. Any output variable in this example will be bound to a list of strings collected by the JSON path syntax.
To learn more about JSONPath syntax check the official documentation here.
5. Save your API connection and go to the bot to which you would like to add a dynamic carousel.
3.2 Set up of the bot scenario
1. In your bot scenario, add a card of type API connection and choose the API connection configured in the previous steps. Don’t forget to choose the latest version of the API connection.
2. If you defined an input in your API connection like in our example, you will see a field to define the question you would like to ask your visitors. In our example, the question is “What type of product are you looking for?”
3. In “Next step after answer” configure to continue to a new step of type “rich message”.
4. In your rich message card write some text to introduce your carousel and click on the “carousel” icon.
5. Choose the “Dynamic” carousel type and fill out the fields with the variables configured earlier in your API connection. Use the “add variable” icon in each field to see available variables. If you don’t see your variables, it means something wasn’t configured correctly in your bot scenario between the API connection card and the rich message card.
6. Preview your carousel and make sure everything works correctly.
