Back-end integration with an API plugin

Enrich your conversational platform with data available from your services.

Setting up

The API plugin can be found in the Action action dialog state. As shown in the image below you can add an API link by clicking on Action - API.

Let's start by selecting the request method for our endpoint. In this example we are going to cover the a POST request but you also choose for GET or DELETE.

Query parameters

Now we can continue by setting up our (optional) query params. These parameters are added as a query string to your URL, for example: https://your-url.com?source=Chatlayer The same example is also illustrated below.

Body parameters

You can only define a request body when your request method is POST or DELETE

In the query we have covered the text type but you actuality can choose three different types inside both your body and query. In the body example we are going to cover all types.

  • Dialogstate can be used to submit the id of a dialogstate to your API. This can be useful if your API decides what the next dialogstate will be.

  • Variables from the Chatlayer platform can be sent to the API.

  • Regular text can also be sent to the API.

The keys that will be used in the body of your API request can be set as shown above.

Result/Result

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:

  1. Session variables: This allows you to set variables in the Chatlayer environment. For choo choo you can use the API for example to overwrite the contents of the locations variable in Chatlayer. You can for example have the locations.destination overwritten. Note that you cannot set the locations variable itself but only it's members.

    1. Namespace: This is the name of your variable, so in this example it is locations.

    2. Data: In the data field you can include your variables. In this example data will contain the member destination and its respective new value.

  2. Messages: You can use this tools to have the API reply actual messages that the bot will send back to the user. It allows for returning multiple versions of a message in case you want to the bot to randomly send a different message. Note that you will have to do the translations of these messages in your API.

  3. Actions: With actions you can define for example the next dialogstate in your conversation. Note that you should send the id of this dialogstate through a query or body parameter as shown above.

The above 3 options are executed In the order shown above. So session variables are set first, then messages are sent and then you will jump to the next dialogstate. You can find an example JSON for these 3 cases in the code snippet below.

post
Your example API

http://your-url.com/?source={source}
This is an example of how your API you should respond. Check the response tab for an example on how to structure your responses to successfully utilise all the strengths of this plugin.
Request
Response
Query Parameters
source
required
string
Source of where the request is being called
Body Parameters
administration
optional
string
ID of the administration dialogstate
user
required
object
User object containing firstname and nickname
200: OK
All three possible responses combined.
{
// Session object sets namespace.variable to value 123
"session": {
"namespace": "namespace",
"data": {
"variable": "123"
}
},
// Messages are being sent to the user.
"messages": [
{
"type": "text",
"config": {
"textMessages": [{ "text": "random message 1" }, { "text": "random message 2" }]
}
}
],
// Navigates to the next dialogstate.
"action": {
"nextDialogstate": "dialogstate-123-abc"
}
}
‚Äč

For more information and documentation contact our support team or your project manager.