Last year I wrote an article about using a combination of Ask for Details and API Calls in Zendesk Bot Builder to built a little Movie Bot based on the Open IMDB API.

Flow Builder - Ask for details

The new Ask For Details option in Flow Builder allows you to pull in contextual information via API into your Zendesk Chat Bot.

Internal NoteThomas Verschoren

That bot turned out great, but it was always limited by the features available in Bot Builder. Or more specifically, the lack of support for arrays and variables inside of the API calls made it impossible to chain API commands. So once a user picked a movie, I couldn‘t do anything based on that choice with another API call.

Now, almost a year later, Zendesk announced Dynamic Conversation Experiences for the bot, which greatly expand the features available in API calls with the addition of three new options:

• Support for Arrays in the API call so that we can more easily iterate over a bunch of results
• The Carousel step can now handle variables and arrays
• We can use variables inside of API calls

So let's dive in and build a better version of the Movie Bot!

What we're building

We're going to build a Zendesk Bot that will first ask the customer for a movie title.

We’ll then use IMDB to retrieve a list of movies that match. When the user selects their movie, we'll show the genre, director and a short summary of the movie, and ask if this resolved their question.

Under all this we make use of a couple of Zendesk Bot step types:

• We use Ask for Details to ask for a movie title and store it in a custom field
• We use the API call step to make two API calls to search and get details from IMDB
• We use a Carousel step to show a list of search results, and use variables to set images, buttons and content
• We use Send Message with its image and button support to show the movie details and guide the customer
• We use Ask if question resolved to wrap up the Answer flow.

Preparing your setup

We assume you already have a working Zendesk Bot setup for this tutorial.

Ask for Details

This Answer Flow requires one custom ticket field to get started. So create a text field called "Movie", that's editable for end-users. We'll use this field to store the search query of the customer. E.g. Alien.

Bot Builder has a nice visual editor, so we don't need to store or remember the Field ID this time!

The API Calls

This bot will make use of Open IMDB to search and query IMDB and retrieve movie info. You can retrieve a free API key from their website.

We're going to make two API calls to first search for a movie based on the input in our custom field, and then get the details for that movie.

Search for a movie

A GET to https://www.omdbapi.com/?s=star%20wars&apikey=abcd1234 with s=star%20wars as your search query and abcd1234 as your OMDB API Key.

The API call returns an array of results. With the new Dynamic Conversation release this array can now be stored as a variable, and we can show a list of all results!

{
    "Search": [
        {
            "Title": "Star Wars: Episode IV - A New Hope",
            "Year": "1977",
            "imdbID": "tt0076759",
            "Poster": "https://m.media-amazon.com/images/M/MV5BOTA5NjhiOTAtZWM0ZC00MWNhLThiMzEtZDFkOTk2OTU1ZDJkXkEyXkFqcGdeQXVyMTA4NDI1NTQx._V1_SX300.jpg"
        },
        {
            "Title": "Star Wars: Episode V - The Empire Strikes Back",
            "Year": "1980",
            "imdbID": "tt0080684",
            "Poster": "https://m.media-amazon.com/images/M/MV5BYmU1NDRjNDgtMzhiMi00NjZmLTg5NGItZDNiZjU5NTU4OTE0XkEyXkFqcGdeQXVyNzkwMjQ5NzM@._V1_SX300.jpg"
        },
        ...
  ]
}

Get movie details

A GET to https://www.omdbapi.com/?i=tt123456&apikey=abcd1234 with tt123456 being the IMDB ID of the movie we found in the first step, and abcd1234 your OMDB API Key.

Similar, we can now use the imdbID of whatever the user choose in the carousel from the search results in our API call, something new that's only become possible since this new release.

The API call returns movie details:

{
    "Title": "Star Wars: Episode IV - A New Hope",
    "Genre": "Action, Adventure, Fantasy",
    "Director": "George Lucas",
    "Plot": "Luke Skywalker joins forces with a Jedi Knight, a cocky pilot, a Wookiee and two droids to save the galaxy from the Empire's world-destroying battle station, while also attempting to rescue Princess Leia from the mysterious Darth ...",
     ...
}

Setting up the bot

Now that we've got the basics figured out, it's time to setup the bot.

Starting

To get started, create a new Answer in your Zendesk Bot.

After the welcome greeting, add an Ask for Details step and select your Movie Ticket Field we created earlier.

Searching for movies

Next, add a Make an API call step that has the following endpoint URL: https://www.omdbapi.com/?s=&apikey=abcd1234. Next, put your cursor right after s= and click the {+} button to select your Movie custom field.

You can then use the Make API Call button to test the API call. If successful, you'll get a list of variables. Save the Search Array and give it a name like results. This variable will contain a list of results, and can be one, two or (any) length.

Once you created the array, you can set a specific name for each internal element of the array via the Name - Value fields. You can define as many items as needed, but we'll use these 4 in the next step: title, year, id and poster.

Displaying the results

Before the new Dynamic features we could not show or handle an array of data, especially when that array had an unknown length. Like shown in my original Ask For Details article, we could only store e.g. results[0].title as a variable, but couldn't account for results[i].

Now we can by making use of the support for variables and arrays in the Show Carousel step:

When you add a Carousel, you can now choose to populate the data with a Dynamic message based on API Data. Select Use array variable, and select your results variable. You can then access all elements in the array to fill out your carousel, by clicking the {+} button in each field.

• Title: results.title will create a carousel element for each movie in our results and set the title to the, well, title.
• Description: results.year to display the release year
• Image: this is a big one, cause we never were able to use variables in images before either: search.poster, containing the URL of the movie poster.

To complete the carousel we'll also add two buttons:

• See on IMDB will concat https://www.imdb.com/title/ and search.id to show how we can combine variables and regular text to create dynamic links
• View Details will save the option chosen by the customer in a new variable chosen_movie which we'll use in the next step. You can do this by choosing Save Response in the Button action dropdown, and setting the name and value of the new variabel to chosen_movie and search.id via the {+} respectively.

The result is a carousel of movie posters, with the title and two buttons below it.

Getting movie details

Once the customer has chosen an option in our carousel by clicking on the View Details button, we can use the new chosen_movie variable to make a second API call and pull in more movie details.

Use https://www.omdbapi.com/?i=&apikey=abcd1234 as the endpoint and use the {+} button to add chosen_movie as a parameter after the ?I= part of the URL. This will make our API request dynamic by referencing the earlier customer choice.

Once you make a sample API call, we can store the variables we need to show them to the customer. Note that this API call does not return an array but a single movie, so we can store variables directly but can't define an array this time.

I stored the genre, director, title and plot as variables to use.

Showing the details

Finally we come to the end of the bot flow. We can use the Show Message step twice to show the customer information about our movie, including its plot in a second message.

The result

The end result is a more complex Zendesk Bot flow that can account for variable sets of returned data, and interact with customer choices to make new API calls.

This demo makes use of the new features to show movies, but you can use this flow to get a list of orders for your customer, and allow them to then chose an order and cancel, refund, or get delivery statuses for that order.

Or you can search your webshop for matching products, and show a carousel of products. When a customer clicks on one in the carousel you can then link them to the buying page, show more information, or offer a way to contact your Support team.

You can test the full flow via the proactive message that should have appeared bottom right, or by choosing the Movie Bot 🍿 in the suggested answers list of the widget.

Conclusion

I've build a lot of bots on this blog and for customers these last few years, and where the Zendesk Bot used to be a very limited hardcoded flow, the additions of metadata, authentication, carousels and API calls gradually made the Zendesk Bot a lot more powerful.

This last new addition brings yet another set of API features that were sorely missing to interact with external APIs.

Is there stuff missing? Sure. I would love to be able to filter what's shown in a carousel, or to transform returned data (capitalise text, replace strings, ...) or map data to other values before showing it to the customer. Or writing a customers' choice in a carousel to a custom field so it's visible to agents and actionable in triggers upon escalation.

But I'm sure we'll see some of these remaining requests being fulfilled sooner rather than later, given the current speed of innovation in the Zendesk Bot.