APIs — All You Need To Know As A Conversation Designer
It’s lunch, and you’re hungry. Now.
You ask your favourite conversational app: “Give me a list of the restaurants close to me.”
Seconds later, you hear:
“I found a few restaurants nearby: Maya Bay Thai snack bar 0.4 miles away on Carlton St, Gushi Japanese Street food 0.3 miles away on Gerrard St, and Ackee Tree Dynamite Jamaican 0.2 miles away on Queen St. Would you like to know more about one of them?”
This bot response illustrates several challenges for Conversation Design when working with dynamic data, or information that changes based on circumstances (such as your current location):
- Imagine that you are in a neighbourhood with many (10+) options. How should the bot surface so many results to the user?
- What were the criteria used to choose the three restaurants in the response? And how does the user access the rest of the options?
- How should the information be presented to the user to help them make a choice?
In this article, we will review where the data that applications use comes from, and how Conversation Design frameworks can be used to craft a good user experience with dynamic data.
What are APIs?
A swimming pool reservation app should be able to handle simple requests, such as “I want to book an appointment this week”. But to do this, the application needs to know a lot of information, such as what reservations are available and when.
Without a bot, you might:
- Call the swimming pool management every time you need to make a reservation
- Book a recurring appointment daily or weekly
But this means the office managing the swimming pool must have a person available to answer your calls, which stops them from offering 24 hours / 7 days a week service.
Or life happens and that ongoing booking you made needs to be canceled one or two days, or changed manually.
This example is a simple demonstration of why APIs exist.
API stands for Application Programming Interface. It’s a combination of protocol (similar to instructions) and software that allow computer systems to interact with each other.
The main use case for an API is to allow one central information technology (IT) system, to expose their data in a secure way for other IT systems to manipulate in real-time.
In our swimming pool example, the data is the list of available dates and times, or a list of open slots. This data is owned by the swimming pool’s management information system. Any authorized applications that want to book or alter appointment slots can do so by accessing the data with an API.
Although they can have many shapes and forms, APIs are usually formatted to look like URLs. For example, the swimming pool API URL might look like: “https://api.swimmingpoolmanagement.io”.
For some APIs, it’s possible to go to the URL, like you would do with any link. You would see the data in your browser, which might look like this music story generator. For other APIs, you need to use a process to access the data. This often requires some programming or the use of no-code tools, such as Zapier.
This is where the IT systems come in. They need to have certain credentials that can securely access the information in the API. Once accessed, the information shared by the API can then be used by an app to accomplish tasks, such as booking a reservation at your local swimming pool.
How are APIs used in Conversational AI?
Any application that uses an API can perform four main tasks with the data available:
- Retrieve data
- Create new entries
- Update existing data
- Delete entries
If we look at our swimming pool reservation app example, the API can be used to access data, and then allow someone to:
- Retrieve available slots
- Create a booking on an available slot
- Update a booking
- Cancel and delete a booking
Conversational applications will use APIs during dialog management, which is the process that allows an agent or bot to build the response that will be returned to the user.
First, it collects information from the user’s request and uses that to filter data from the API. The information from the API is then presented to the user, depending on what the response is.
Continuing with our example, when the user says: “What are the available reservations on Monday morning?”, the conversational application will:
- First, extract the slot bookingPeriod (see our article about slots) “Monday morning”.
- Second, call the reservation API to retrieve all the available slots on Monday.
- Third, search the data available via the API to find what slots match the user’s request.
- Finally, it will present the user with the best options and deliver a response. This may sound something like: “There are two available spots next Monday, one at 8 and the other at 9. Would you be interested in booking one of them?”
Designing conversation with dynamic data
The final step in the process of using an API in conversational AI is presenting the options. This step is also the most challenging.
The data in an API is dynamic, which means it will vary based on usage. If a user asks “What are the available spots this week?”, one week, the API might return that there is only one opening available, but next week there might be a spot open every day.
Someone using the app won’t have a reason to know this, and even though the bot can access this information through the API, it’s technically not part of the original request.
We recommend a specific framework when working with a conversational application that integrates with an API:
- Design the choices
- Design for “no results”
- Design the filter prompts
Design the choices
This means designing for favourable outcomes, which is when the API returns a limited number of options. This is usually between one and three choices, since, as Jonathan Bloom points out, it’s easier for the human brain to remember up to three options.
The conversational application can then present the choices to the user for a decision.
For example, when asked for available spots the agent searches the data and finds three openings: Monday 8 to 9, Tuesday 8 to 9, and Friday 9 to 10.
It can then respond:
“There are three available reservations this week, Monday at 8 am, Tuesday at 8 am, and Friday at 9 am. Would you like to book any of them?”
Design for “no results”
When the API returns no results, it is crucial to always craft a prompt that offers a solution.
A response that says: “There are no reservations available this week,” for example, is not helpful.
Instead, the agent can offer a way for the user to progress in the conversation by saying something like: “All the appointments this week have been booked. Would you like to check for next week?”
Design the filter prompts
When the API returns more than three options that meet the user’s criteria, design a response to investigate approaches. This can be done by asking more questions to the user, thereby further filtering the results.
These filters need to be specific to the data.
In our example, each reservation would have a date and a time. If the API returns twenty results, one possible response could be: “There are a lot of openings this week. Do you have a preferred day?”
Following the user response, the application will be able to refine further until it meets the requirements for a favourable outcome. At this stage, we can design the choices.
Conversation Design 🤝 Engineering
Defining how a bot will respond to dynamic data provides a framework that engineering and dev teams use to build an API integration.
When it comes to creating documentation and guidelines, Conversation Designers need to contribute, especially when it comes to defining dynamic prompts.
This is part of the practice of Conversation Design, and is covered in our Foundations in Conversational Experience Design (FCxD) course (next cohort starts October 4th).
As part of the course, we review working with stakeholders, team collaboration, and the entire handoff process, in addition to gaining experience with different no-code tools.
If you liked this story, please give us a clap 👏👏🏻👏🏽.
Feel free to share in the comments if you have other strategies to design for dynamic data or your own questions about APIs and conversational design.
