Use API connections in bot scenarios

Once your bot is connected to an API, you are now able to integrate that connection into your scenario. Thus, your bot will be able to collect or deliver personalized information to your visitors autonomously, making your human respondents more available for more advanced exchanges.

Your bot can use this connection to an API in two ways: either to collect information and send it to an API, or on the contrary to deliver information retrieved from an API to its interlocutors. This article explains how to integrate these two uses into its scenario.

1. Collect data within your bot scenario and send it to an API connection

Step 1 - Create a card of the type “API Connection” in your bot builder scenario

  • You can create a new bot or edit an existing one



Step 2 - Set the right API connection

  • In the field “Select an API connection” choose the API previously configured
  • Choose the latest version in the “choose the version” field



Step 3 - Configure the inputs expected from the visitor

  • For each input write a short question that the bot will ask visitors.
  • You can check the box “If the answer already exists, don’t ask the question” if there is a probability that the visitor would have provided that information in a previous question in the scenario*
  • Choose the next step in the scenario after the visitor replies and the alternative in case of API request failure action in case the bot fails to make an API request
  • The answer of the user will be sent automatically to your API as per the mapping section defined in your API connection
  • Choose the next card of your scenario and continue building your scenario as usual



*This option will avoid that if the question was asked already in a previous API connection or open question card in the scenario that it will be asked again.
Also, it is useful when you need to connect to multiple API's in the same bot scenario and one API card can use the information already asked from the visitor in another API card.


Please note the following reasons the alternative in case of API request failure action would be activated  (a non-exhaustive list).

There is no response from the connected API:

  • URL incorrectly configured in API connection
  • API needs an ID token

There is a response but misconfigured in API connection or client API:

  • Misconfigured JSON path in API connection
  • Empty variable

A problem with the visitor’s text:

  • If the text of the visitor is not in the configured response format (text, amount of money, distance, duration etc)


2. Deliver data from an API connection within your bot scenario

Step 1 to 3 are exactly the same as the first case

Step 4 - Return a dynamic and personalized answer from API results

  • Choose a “rich message” card as the next card of your scenario and write an answer to the question asked in Step 3
  • Include in your answer a variable from the API by either clicking the “add variable” icon or simply typing { symbol to see a choice of variables to include.
  • Choose the next card of your scenario and continue building your scenario as usual



Reminder: since your API connection really works, any information you send to an API during your tests will be added to it “for real”!