API Connection: using them in a Bot scenario

To take the automation of your conversations even further and give your customers greater autonomy, you can connect your bot to an API, then use this connection and the information in its scenario. The first article describes the technical aspects and the initial connection to the API. The article below details the possible applications.

Bot & API: applications

To date, you can use APIs in different ways in your scenario:

  • by asking visitors an open-ended question to collect information that will be stored in the API (for example, by asking them for their email address to create a customer account) - to do this, use the "API connection" card.
  • in the other direction, by interrogating an API and retransmitting information to visitors (for example, by giving the order status corresponding to a tracking number previously transmitted by visitors).
  • by presenting them with a choice of products or services in the form of a carousel of images and text sourced from the API (for example, to highlight gift ideas or star products) - to do this, use the "Rich Message" card by choosing the "thumbnail or carousel" option, then "dynamic".
  • by offering them multiple choice questions automatically generated in an API (for example, to help them find a product using a product list API) - to do this, use the "Multiple choice question" card by choosing the "dynamic" option

Useful concepts

An API is a technical resource that often requires the intervention of developers in order to function. Here are a few terms to get you started:

Variable

  • a variable is a kind of "box" used to store values in various forms (numbers, text, images, etc.),
  • during exchanges between your bot and your API, you can create, name, save or retrieve different variables,
  • for exchanges between the API and your bot to work properly, you need to use strictly the same nomenclature - for example, use {email_adress} if that's the nomenclature used by your API, and not {emailadress}.

Value or technical value

  • a value is specific data stored in a variable - for example, if a visitor gives their email address to your bot, it becomes a value, stored in the {email_adress} variable. This variable can contain a large number of email addresses from many different visitors.
  • it is possible to re-use a value at different points in a bot scenario, which avoids asking the same question several times over the course of a conversation - for example, the {email_adress} variable can be used to store a visitor's email address in your API. Later on in the conversation, the bot can re-use the stored address in a message such as "You will be notified of the delivery to the following email address {email_adress}".

Message displayed or value displayed

  • variables and values pass between the API and the bot in the form of a technical nomenclature,
  • as this nomenclature is not very intuitive for your visitors, iAdvize allows you to write more understandable messages in the fields entitled "displayed message" or "displayed value" in the cards of your scenario.

Alternative if the request fails

  • it can happen that an API request fails and you are unable to exchange information with your API,
  • the main reasons for request failure are detailed in this article,
  • from each card in your scenario, you can program an alternative so that your bot can continue the conversation even if the request fails.

Gather visitor information

With an open question and the "API connection" card

In your bot scenario, create an "API connection" type card

Type-cards-Api-connection.png

Select an API from those configured by your team, then choose its latest version. The card will automatically detect the variables configured for this particular connection.

Write an open question corresponding to this variable, which will be visible to your visitors.

You can tick or untick the "don't ask this question if the bot already knows the answer" box: this way the bot won't ask the visitor for a value again if it already knows it earlier in the conversation.

Cards-Connection-API-EN-Check.png

When the bot and the visitor exchange, the bot will store the value given by the visitor in the variable provided by the API connection. Then choose the next step as in any other map.

Don't forget to configure an alternative in case the API request fails!

With a multiple choice question and the "MCQ" card

In your bot scenario, create a "multiple choice question" type card.

Choose a "static" content type.

Create your visitor choices.

You can save the visitors' choices in a variable so that you can reuse them in your scenario.

You can also send this variable to an API by creating an "API connection" card in the next step. Remember to respect the nomenclature provided by your API.

MCQ_-Static-Save-variable.png

Customise your scenario with content from an API

With the "rich content" map

In your bot scenario, create a "rich content" type card

In the input field, type the text that will be visible to visitors, then add a variable by clicking on the "add variable" icon or by typing the { symbol to display the list of available variables.

Then choose the next step as for any other card.

Card-rich-message.png

The "rich content" card also lets you display images and dynamic content from an API in the form of a carousel. More details in this article.

With the "multiple choice question" card

You can also deliver content from an API in the form of multiple-choice questions, for example to guide your visitors through a product catalogue.

In your bot scenario, create a "multiple choice question" type card

Choose a "dynamic" type of content - you can also enter choices manually and thus mix static and dynamic choices.

Select the displayed value (the one your visitors will be able to read), the technical value (the code sent to the API), and the next step for each choice.

You can display up to 13 choices, but we agent you to restrict your choices for better readability.

You can save the visitor's choice in a variable for reuse in your scenario.

You can also send this variable to an API by creating an "API connection" card in the next step. Remember to respect the nomenclature provided by your API.