You can make extensive API calls to any external system to fetch or push data and display it as part of the bot conversation. You do not have to pass parameters every time you trigger an API call from a dialog. Instead, you can configure them once in the API library, and reuse them in any of your dialogs.


TABLE OF CONTENTS


A quick guide in creating a new API:


  • Go to Bots from the left pane.
  • Create a new bot or select the bot you want to edit.
  • Navigate to Flows > Configure > API library



  • 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 make use of placeholders using the + icon on the bottom right.


  • Add Headers: You can authorize your APIs in this field and also 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, 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 from any dialog in the chatbot conversation. 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. On this page, you can see the list of APIs that you have configured. Apart from this, you can:

  • Search for the APIs that you have already configured
  • View the type of actions set up for the API to perform (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’s response through a message, action, or even using 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 are creating 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 the list of 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 before it. 
  • Similarly, if you need to trigger the API after a message, create the Trigger API action after it.



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 r    esponse 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: only REST APIs with JSON response is supported.


Note: API requests will time out after 10 seconds if a response is not received.


Please write to freshbots-support@freshworks.com if you have any more questions; we’ll be happy to help you.