API integration
This document describes how to integrate Chatlayer.ai with your back end or third party services in order to share data gathered in the conversation with the bot, or enrich the bot with data captured
Please note that the term dialog state refers to the same thing as block, in the context of development tools.
How custom integrations work
Chatlayer provides a solution to integrate your conversational agent with your own backend business logic, APIs, and databases to create contextual, personalized and actionable conversational experiences for your users.
A Chatlayer API widget is available in the Action blocks to enable you to create chatbot messages based on user-specific information and other external data, and to redirect your users to different conversational flows based on your own business logic. You can use this solution on any platform that supports receiving and responding to HTTP requests.
A user types and sends a text message from a conversational agent interface channel like Facebook Messenger, Web chat, … to Chatlayer.
The received message is going through Chatlayer’s NLP engine to detect the intent and the returned intent combined with user context will be used to retrieve the next block in the conversation.
Chatlayer’s API plugin can be added in a block to send an API request to your server with different types of static data and/or user session data.
Your server can respond with an object with three fields:
session: a session object for saving retrieved user session data
messages: an array of messages to send back to the interface channel
nextDialogstate: a block state identifier to redirect the user to a next block in a conversation flow.
Please note that the term dialog state refers to the same thing as block, in the context of development tools.
Session data will first be stored in the user session so that you can use this data in messages defined in the array of messages or in messages defined in a dialog state defined as nextDialogstate
in the API response. Second, messages will be sent, and afterwards the user is redirected to the nextDialogstate
. All fields are optional.
API Action step
Chatlayer provides an API step in the list of Action steps which you can configure in dialog state in one of your conversational flows.
![](https://docs.chatlayer.ai/~gitbook/image?url=https%3A%2F%2F2786867680-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LLTwFwbOqJj4dDhg8Ju%252Fuploads%252FyKxJITNKYZAjbuH1Tcud%252FScreenshot%25202024-07-31%2520at%252017.17.05.png%3Falt%3Dmedia%26token%3D9f7ab17c-18e0-4cea-9abe-98dd59b0655a&width=768&dpr=4&quality=100&sign=45821312&sv=1)
Configuration of the API
The API plugin sends a request to your back end server.
Settings
It supports different configuration settings:
HTTPS method
API endpoint url
Query parameters
Body payload (JSON)
Configuration (link to API SSL/HMAC settings)
HTTPS methods
The plugin supports three HTTPS methods
POST
GET
DELETE
PUT
PATCH
![](https://docs.chatlayer.ai/~gitbook/image?url=https%3A%2F%2F2786867680-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LLTwFwbOqJj4dDhg8Ju%252Fuploads%252FM0WioxVYquol52FeSJ93%252FScreenshot%25202024-07-31%2520at%252017.19.35.png%3Falt%3Dmedia%26token%3D200e9763-fb92-4a3f-a531-809e4240e654&width=768&dpr=4&quality=100&sign=53d14133&sv=1)
Payload parameters
Under the Query and Body tabs, add query parameters and/or a body payload by defining key value combinations. Each key can have three possible value types:
text: static text
variable: a user session variable. The value of the variable will be stored as value for the key. Dot and array notation are supported, for example:
users[0].firstname
dialogstate: select a dialog state from the dropdown. The dialog state id will be stored as value for the key. This id can be used to redirect the user to a certain dialog state based on your business logic when sending back the API response.
![](https://docs.chatlayer.ai/~gitbook/image?url=https%3A%2F%2F2786867680-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LLTwFwbOqJj4dDhg8Ju%252Fuploads%252FfgoSheW6uaQ19viwIJPu%252FScreenshot%25202024-07-31%2520at%252017.27.35.png%3Falt%3Dmedia%26token%3Dc856337c-7ee1-4d00-a190-7eee84fb7ca5&width=768&dpr=4&quality=100&sign=87f1fead&sv=1)
You can only define a request body when your request method is POST or DELETE.
Body
Body is where you can define a request body request in all HTTPS methods.
Example
In this example, representing a money transfer, we send five keys in the body payload of an HTTPS POST request to our API endpoint https://chatlayer-integration-demo.glitch.me/transaction.
![](https://docs.chatlayer.ai/~gitbook/image?url=https%3A%2F%2F2786867680-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LLTwFwbOqJj4dDhg8Ju%252Fuploads%252FFE28tsRMUl78q6lPu6H1%252FScreenshot%25202024-07-31%2520at%252017.23.44.png%3Falt%3Dmedia%26token%3Def255adc-ab28-469e-a79d-c673b5322f94&width=768&dpr=4&quality=100&sign=563ee0e9&sv=1)
The amount key will have the value of user session variable transfer_amount (ex: 500).
The destination key will have the value of user session variable transfer_destination (ex: Elon Musk).
The accountType key will have the value of user session variable card_type (ex: savings_account).
The transactionSuccess key will have the dialog state identifier for the ‘successful transaction’ dialog state. This identifier can be used in the response of this API request to redirect the user to a new dialog state.
The transactionNoMoney key will have the dialog state identifier for the ‘unsuccessful transaction’ dialog state. This identifier can be used in the response of this API request to redirect the user to a new dialog state.
The test key will have a value of ‘5’.
This will result in the following body payload
Authorization
The Authorization tab has the following components:
Basic auth: will display the fields to fill username and password.
![](https://docs.chatlayer.ai/~gitbook/image?url=https%3A%2F%2F2786867680-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LLTwFwbOqJj4dDhg8Ju%252Fuploads%252FR4sXoFbrZd5VFK0y8eI3%252FScreenshot%25202024-07-31%2520at%252017.31.44.png%3Falt%3Dmedia%26token%3D1cdd6ef7-023f-4385-982e-a21f9254c6dd&width=768&dpr=4&quality=100&sign=b53f8903&sv=1)
Bearer token: will display the Token field to be filled in.
![](https://docs.chatlayer.ai/~gitbook/image?url=https%3A%2F%2F2786867680-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LLTwFwbOqJj4dDhg8Ju%252Fuploads%252FNhzfHPODSUdvg8htRZz9%252FScreenshot%25202024-07-31%2520at%252017.32.54.png%3Falt%3Dmedia%26token%3D047fb08a-26e8-4a31-b021-beccbc2f1c64&width=768&dpr=4&quality=100&sign=1e416a55&sv=1)
Headers
The Headers tab is where you configure your headers.
![](https://docs.chatlayer.ai/~gitbook/image?url=https%3A%2F%2F2786867680-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LLTwFwbOqJj4dDhg8Ju%252Fuploads%252FyS2K1FFePNECtgjXlkk1%252FScreenshot%25202024-07-31%2520at%252017.40.06.png%3Falt%3Dmedia%26token%3D100aba4a-21e0-4c12-b1f5-37f826276a24&width=768&dpr=4&quality=100&sign=e0610402&sv=1)
Configuration
Configuration is where, if you have an API configuration in Settings>API, you will see them here.
![](https://docs.chatlayer.ai/~gitbook/image?url=https%3A%2F%2F2786867680-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LLTwFwbOqJj4dDhg8Ju%252Fuploads%252FziXYuUIRnpR2tmgKSNUZ%252FScreenshot%25202024-07-31%2520at%252017.40.51.png%3Falt%3Dmedia%26token%3D28029046-261c-4fae-aada-41c8ad5f000d&width=768&dpr=4&quality=100&sign=aab0dca9&sv=1)
Multi-language
If the API response will send agent messages back to the user and the agent supports multiple languages, don’t forget to send the user language in the request. The user language is available in the user session variable ‘locale'. Your back end service can use this language setting to send back the response in the user his preferred language.
Sending the API response
You do not need to configure the API plugin to listen for a response. This is done automatically and the API plugin will listen for what your API returns. The API plugin supports 3 types of return variables:
session: A session object for saving data in to the user session. The session has two mandatory fields:
namespace: a key namespace. The data object will be stored in this namespace key in the user session. You can access this object in Chatlayer.ai by using interpolation: {namespace.dataKey}
data: an object which will be saved in the user session data in the namespace key.
messages: an array of messages to send back to the user interface channel. The structure of different message types such as text, buttons, quick replies, carousels, lists, media, … is available in the chat message structure.
action: an object defining an action such as redirecting the user to a next dialog state in the conversation.
nextDialogstate: a dialog state identifier to redirect the user to a next dialog state in the conversation flow.
The above 3 options are executed in the order shown above: session variables are set first, then messages are sent and then you will jump to the next dialog state. You can find an example JSON for these 3 cases in the code snippet below:
Make sure you include the correct content type in the header: content-type: application/json;
Example
This example demonstrates one API endpoint for transferring an amount of money from an account type (regular or savings) to someone. We will redirected the user to a certain dialog state based on the transaction result.
We receive the body payload object as defined in the Chatlayer.ai API plugin. If the user doesn’t have a sufficient amount of money on his account we set the next dialog state to ‘transactionNoMoney’. Else we subtract the desired amount and set the next dialog state to ‘transactionSuccess'.
As a response for the request we send the next dialogs state to redirect the user to that state and we save the amount of money and the limit of his account in his session data under the namespace account. This data can be used in that next dialog state.
![](https://docs.chatlayer.ai/~gitbook/image?url=https%3A%2F%2F2786867680-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LLTwFwbOqJj4dDhg8Ju%252Fuploads%252F0lmJ7m1N9ODKxojysxyz%252Fimage.png%3Falt%3Dmedia%26token%3D0478872f-c4d1-442b-bb1b-a5f401cd4a1f&width=768&dpr=4&quality=100&sign=cf716fe7&sv=1)
As an alternative solution you could also send that chat message as a response of the API plugin requests by using the messages key.
You can have a look at the code of our mock banking backend here. Feel free to reuse parts of this project to create your own custom Chatlayer.ai integrations.
Last updated