Application API

The Application API in Kindly offers even further integration towards third-party services. Using the API lets supported service communicate with your customers through the Kindly platform.

Getting started

New application

To start using the Application API with your bot, you first need to let us know about your application.

  1. From the dashboard of your bot, expand Connect in the sidebar menu and click Application.

  2. Click Add new.

  3. Enter a descriptive name for your application and click save.

  4. Click Show API key and copy it.

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

To start receiving webhooks enter your endpoint in the Webhook URL field under Settings. Kindly will POST to this URL. Now you are ready to start testing your 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:

{
"user_id": "Unique user id",
"message": "Hello bot!"
}

The response to the request will contain a unique id of for 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.

{
"chatmessage_id": "some hexadecimal id"
}

Example:

curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"user_id": "UNIQUE USER ID", "message": "Hello world!"}' \
https://bot.kindly.ai/api/v1/send

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:

{
"user_id": "Unique user id"
}

Example:

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

Takeover request

If your user takes an action that should trigger a takeover 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:

{
"user_id": "Unique user id"
}

or

{
"chat_id": "ID of the chat requesting takeover"
}

Example:

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:

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

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:

{
"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"
}
],
"image_carousel": [
{
"altText": "This is the image alt text",
"linkUrl": "https://example.com",
"imageUrl": "https://example.com/image.jpg",
"description": ""
}
]
}

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:

{
"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.

{
"chat_id": "some hexadecimal id"
}

Example:

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: {}`.

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 lets 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.