You can make extensive API calls to any external system to fetch or push data and display it to your customers while interacting with the bot. You can configure them once in the API library and reuse them in any of your dialogs in that bot.


TABLE OF CONTENTS


Quick guide to creating a new API

  • Navigate to Chatbots > select your bot or create a new one > Flows > Configure > API library.



Note: If you have the cURL details of an API or a Postman collection (version 2 and 2.1 are supported), you can navigate to Flows > Configure > API library > Import APIs to paste the cURL command or the Postman collection and instantly import the APIs.


  • The +Add new button will allow you to configure a new API call.



Configuring the API

  • Name: Give your API call a suitable name.


  • URL/JS function name: Provide the endpoint URL here. The content picker option [+] in this field will allow you to append placeholder values like customer input, other API responses, default parameters, etc.


  • Method: Configure the type of API call you’re looking to make - GET, PUT, POST, DELETE, or a JS function and then pass the payload accordingly. You can also configure a larger payload content in an expandable text editor that will format JSON automatically when pasted into it. For example, to create a ticket in your Freshdesk account, pass the email, priority, status, subject, and description in JSON. You can also use placeholders using the + icon on the bottom right.



Note: While setting up the method as POST or PUT, you can choose between JSON, Multipart form data, or URL Encoded form as the payload type.

Click here to learn more about multipart forms.




  • Add Headers: You can authorize your APIs in this field and pass any additional parameters as headers in this section.


  • Test: To make sure that you have correctly configured the API call, you can perform a sample test run by checking the Run Test checkbox and pass test values for the dynamic fields you have configured in the payload (for PUT, POST, and JSON methods), and verify the response headers.


  • Add or remove the required response parameters: You can reference any attributes from the response headers or chatbot conversation dialog. Add or remove the required response parameters with a click of a button from the test variable responses before running them.




API list page

You can access the API library from Flows > Configure > API library. You can see the list of APIs you have configured on this page. Apart from this, you can use this page to:

  • Search for the APIs that you have configured
  • See the API's actions (GET, POST, etc.)
  • Display when you created the API and when it was last modified.
  • Edit or delete each API, or create new APIs.


A quick guide to using the APIs

You can add an API response through a message, action, or even a condition.


Using Message to add an API response

  • Type out the message or the question to be displayed to the customer.
  • Click on the + icon to access placeholders > APIs.
  • The bot builder will display the list of all the APIs configured under the API library.
  • Choose the required API to append it to the text box.


For example, if you create a ticket for the bot conversation, you can set up a create ticket API call. You can then reference the ticket ID from the response parameters.



Under Actions

  • Create a new action in the dialog
  • Set the Action type to Trigger API
  • Select the required API from all the APIs configured under that bot’s API library.



  • You can insert the Trigger API action anywhere in the flow.
  • If you need to trigger the API before a message, create the Trigger API action.
  • Similarly, if you need to trigger the API after a message, create the Trigger API action.



Under Conditions

  • Open the Conditions tab for the required dialog > click on + icon to access placeholders > choose APIs from the drop-down. 
  • You will see the list of all the APIs configured under the API library.
  • Select the required API call and then proceed to choose the response value.
  • You can use the API’s response both in the body of the condition and in the condition’s value section.



For example: In the case of a simple subscription flow, you can get the status of the payment from the API response and redirect customers to a different dialog/flow if the status is unpaid or set up a dialog to display a simple message to the customers if the status equals paid.


Note: 
1. Only REST APIs with JSON response is supported.
2. API requests will time out after 10 seconds if a response is not received.
3. In case of a Postman collection, we allow a maximum of 20 APIs and files <=20 KB.