APIs
Application API

The Application API empowers you to interact with a bot constructed within the Kindly Platform, bypassing the need for Kindly's native Chat UI.

This functionality facilitates enhanced integration with third-party services. By managing communication through your backend, you can for example seamlessly display chat content within your custom-designed user interface.
Getting started
New application
To start using the Application API with your bot, you first need to let us know about your application.
From the dashboard of your Kindly bot, expand Connect in the navigation menu and click Application.
Click New application.
Enter a descriptive name for your application. You can also add your custom webhook, which is optional.
Click Create application.
You will now see a new API Key, which will act as your bearer token when interacting with the Text Predict API.
Authorization
With the API key in hand, you're ready to start integrating Kindly into your application.
Every request should include the header Authorization: Bearer <API_KEY>
Webhook
As previously mentioned, you can add a webhook to your application integration. You can also add or change the webhook URL after you created the application integration.
Sending and receiving
Sending message
To chat with the bot POST a message to https://bot.kindly.ai/api/v1/send
The POST payload should be in the following format:
JSON
{
    "user_id": "<unique-user-id>",
    "message": "<message>",
    "language_code": "<language-code>",
}
{
    "user_id": "<unique-user-id>",
    "message": "<message>",
    "language_code": "<language-code>",
}
﻿
language_code: is the two letter language code of your bot. This is the ISO 639-1 format of your bots language. For examples:
English: en
Spanish: es
French: fr
etc...
The response to the request will contain a unique id of the message. When the bot sends the reply to the message via webhook, this id will be found in the reply_to_id field of the reply payload.
JSON
{
    "reply_to_id": "some hexadecimal id"
}
{
    "reply_to_id": "some hexadecimal id"
}
﻿
Example:
Shell
curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID", "message": "Hello world!", "language_code": "en"}' \
https://bot.kindly.ai/api/v1/send
curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID", "message": "Hello world!", "language_code": "en"}' \
https://bot.kindly.ai/api/v1/send
﻿
Forcing a followup
Followup dialogues can in general only be triggered right after their parent dialogues. But there are cases when one wants to sidestep this limitation, mainly when using a quick reply button to trigger a followup. Normally the button would no longer work later in the chat, but this can be forced by including the id of the parent dialogue (i.e. the dialogue containing the button) in the payload under the name exchange_id. The id of a dialogue can be obtained from its URL in the platform.
For example, let's say the dialogue with id 9c0dd930-ca7c-4830-a901-7da5ebd3b6a6 has a quick reply button whose value is trigger_followup and it has a followup dialogue with sample or keyword trigger_followup. When the button is clicked the application could send the following payload:
JSON
{
    "user_id": "Unique user id",
    "message": "trigger_followup",
    "language_code": "en",
    "exchange_id": "9c0dd930-ca7c-4830-a901-7da5ebd3b6a6"
}
{
    "user_id": "Unique user id",
    "message": "trigger_followup",
    "language_code": "en",
    "exchange_id": "9c0dd930-ca7c-4830-a901-7da5ebd3b6a6"
}
﻿
Make the bot say hello
You can also trigger the bot's greeting message with a POST to https://bot.kindly.ai/api/v1/greet
The POST payload is the same as when sending a regular message, but without a message:
JSON
{
    "user_id": "Unique user id"
}
{
    "user_id": "Unique user id"
}
﻿
Example:
Shell
curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID"}' \
https://bot.kindly.ai/api/v1/greet
curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID"}' \
https://bot.kindly.ai/api/v1/greet
﻿
Handover request
If your user takes an action that should trigger a handover request, you can do this with a POST to https://bot.kindly.ai/api/v1/request_takeover
The POST payload should contain either a user_id or chat_id:
JSON
{
    "user_id": "Unique user id"
}
{
    "user_id": "Unique user id"
}
﻿
or
JSON
{
    "chat_id": "ID of the chat requesting handover"
}
{
    "chat_id": "ID of the chat requesting handover"
}
﻿
Example:
Shell
curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID"}' \
https://bot.kindly.ai/api/v1/request_takeover
curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID"}' \
https://bot.kindly.ai/api/v1/request_takeover
﻿
Trigger a defined dialogue
Instead of sending a reply defined by the webhook server, you can also trigger a dialogue that you have defined in the Kindly platform.
Examples:
Shell
curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID", "exchange_id": "DIALOGUE ID"}' \
https://bot.kindly.ai/api/v1/trigger
curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID", "exchange_id": "DIALOGUE ID"}' \
https://bot.kindly.ai/api/v1/trigger
﻿
or
Shell
curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID", "exchange_slug": "DIALOGUE SLUG"}' \
https://bot.kindly.ai/api/v1/trigger
curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID", "exchange_slug": "DIALOGUE SLUG"}' \
https://bot.kindly.ai/api/v1/trigger
﻿
The dialogue ID is a 128 bit hexadecimal UUID. You can find it on the page where you edit the dialogue.
The dialogue slug is an optional value picked by you that can be used in place of the dialogue UUID. You can set the dialogue slug on dialogues with the trigger type.
Receiving messages from the bot
Once the bot has a reply to the message, Kindly will POST the reply back to your application at the Webhook URL specified in getting started.
The POST payload from Kindly has the following format:
JSON
{
   "exchange_id":"The unique id of the response",
   "exchange_type":"Greeting, dialogue or fallback",
   "user_id":"Unique user id",
   "reply_to_id":"The chatmessage_id of the message being replied to",
   "message":"Hello world!",
   "buttons":[
      {
         "id":"The button id",
         "type":"Type of button (possible values are 'quick_reply', 'link', 'email', 'phone')",
         "label":"Label of button",
         "value":"Message value when button is activated",
         "exchange_id":"Exchange identifier",
         "new_context":{
            "key":"value",
            "key2":2,
            "key3":null
         }
      }
   ],
   "image_carousel":[
      {
         "altText":"This is the image alt text",
         "linkUrl":"https://example.com",
         "imageUrl":"https://example.com/image.jpg",
         "description":""
      }
   ],
   "form":{
      "submit_dialogue_id":"The submit dialogue id",
      "cancel_dialogue_id":"The cancel dialogue id",
      "language_code": "Language code of the form",
      "texts":{
         "submit_button_text":"Send",
         "cancel_button_text":"Cancel",
         "cancel_text":"Form was exited",
         "error_text":"An error occurred",
         "unanswered_text":"Form was not answered"
      },
      "fields":[
         {
            "input_type": "Type of input (e.g., 'TEXT', 'EMAIL', 'NUMBER', 'RANGE', 'SELECT', 'CHECKBOX', 'RADIO', 'FILE')",
            "required":false,
            "order":0,
            "slug":"Slug for the field",
            "texts":{
               "label":"Label for the field",
               "placeholder_text":"Placeholder text for the field"
            }
         }
      ],
      "submission_id":"Unique identifier for the form submission"
   }
}
{
   "exchange_id":"The unique id of the response",
   "exchange_type":"Greeting, dialogue or fallback",
   "user_id":"Unique user id",
   "reply_to_id":"The chatmessage_id of the message being replied to",
   "message":"Hello world!",
   "buttons":[
      {
         "id":"The button id",
         "type":"Type of button (possible values are 'quick_reply', 'link', 'email', 'phone')",
         "label":"Label of button",
         "value":"Message value when button is activated",
         "exchange_id":"Exchange identifier",
         "new_context":{
            "key":"value",
            "key2":2,
            "key3":null
         }
      }
   ],
   "image_carousel":[
      {
         "altText":"This is the image alt text",
         "linkUrl":"https://example.com",
         "imageUrl":"https://example.com/image.jpg",
         "description":""
      }
   ],
   "form":{
      "submit_dialogue_id":"The submit dialogue id",
      "cancel_dialogue_id":"The cancel dialogue id",
      "language_code": "Language code of the form",
      "texts":{
         "submit_button_text":"Send",
         "cancel_button_text":"Cancel",
         "cancel_text":"Form was exited",
         "error_text":"An error occurred",
         "unanswered_text":"Form was not answered"
      },
      "fields":[
         {
            "input_type": "Type of input (e.g., 'TEXT', 'EMAIL', 'NUMBER', 'RANGE', 'SELECT', 'CHECKBOX', 'RADIO', 'FILE')",
            "required":false,
            "order":0,
            "slug":"Slug for the field",
            "texts":{
               "label":"Label for the field",
               "placeholder_text":"Placeholder text for the field"
            }
         }
      ],
      "submission_id":"Unique identifier for the form submission"
   }
}
﻿
Context
You can also read and write to the chat session's context memory with your API requests. See the context documentation for more information.
Write to context
You can write to context without sending a message to the user. Use a POST request to https://bot.kindly.ai/api/v1/set_context
The POST payload should be in the following format:
JSON
{
    "user_id": "Unique user id",
    "context": { "purchase_flow_complete": true }
}
{
    "user_id": "Unique user id",
    "context": { "purchase_flow_complete": true }
}
﻿
The response to the request will contain a reference to the chat that was updated.
JSON
{
    "chat_id": "some hexadecimal id"
}
{
    "chat_id": "some hexadecimal id"
}
﻿
Example:
Shell
curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID", "context": { "purchase_flow_complete": true }' \
https://bot.kindly.ai/api/v1/set_context

curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID", "context": { "purchase_flow_complete": true }' \
https://bot.kindly.ai/api/v1/set_context
﻿
To clear the context completely, you can supply an empty object context: {}.
Submitting a Form
You can send the results of a form by making a POST  to https://bot.kindly.ai/api/v1/form/submit
The POST payload should be in the following format:
JSON
{
	"user_id": "<unique-user-id>",
	"submission_id": "<form-submission-id>",
	"context": {
		"<slug-field>": "<selected-slug>"
	},
	"state": "<form-state>"
}
{
	"user_id": "<unique-user-id>",
	"submission_id": "<form-submission-id>",
	"context": {
		"<slug-field>": "<selected-slug>"
	},
	"state": "<form-state>"
}
﻿
submission_id: The ID associated with the form submission.
context: Represents the selected form field, including the user's input or selection.
state: Indicates the current state of the form results. Possible states include:
ACTIVE
UNANSWERED
SUBMITTED
CANCELED
ERRORED
Upon successful submission, the response will be structured as follows:
JSON
{
	"form_submission_id": "<form-submission-id>",
	"form_id": "<form-id>",
	"state": "<form-state>",
	"updated_context": {
		"_name": "<API-name>",
		"_organization_name": "<ORG-name>",
		"<slug-field>": "<selected-slug>"
	}
}
{
	"form_submission_id": "<form-submission-id>",
	"form_id": "<form-id>",
	"state": "<form-state>",
	"updated_context": {
		"_name": "<API-name>",
		"_organization_name": "<ORG-name>",
		"<slug-field>": "<selected-slug>"
	}
}
﻿
Try a working example
To show an example of how to use the API, we've set up a live chat application using Docker, Node JS, socket.io and React that integrates with Kindly.
Check out the running demo.
﻿View source code on Github.
Application API vs. Webhooks
At first glance, the Application API and webhooks might look more or less the same. There is, however, a significant difference.
While webhooks let Kindly POST to a predefined URL, the response possibilities are limited. A webhook is not able to send multiple replies to Kindly. Furthermore, it's not possible for a webhook to send a message to Kindly without being triggered to do so. Using the application API you can do just that.
Updated 09 Jan 2024
Did this page help you?
Set up event tracking with Google Tag Manager (GTM)
Chat Widget API