Application API

the application api empowers you to interact with a bot constructed within the kindly platform, bypassing the need for kindly's native widget 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, go to connect > application > new application enter a descriptive name for your application add a webhook url where the answers from kindly will be posted at click create application you will now see a new api key , which will act as your bearer token when interacting with the kindly system 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 every answer from kindly to your application api requests will be posted at the webhook url you provided this url can be edited also afterwards 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" "\<message>", "language code" "\<language code>" } language code is the two language code of the languages supported by your bot (both live translation and managed languages) you can find the supported language codes languages docid\ jtm5dxgyrj99xvjkxgkdv 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 { "reply to 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!", "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 { "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 { "user id" "\<unique user id>", "language code" "\<language code>" } example curl h 'content type application/json' \\ h "authorization bearer your api key" \\ d '{"user id" "unique user id", "language code" "\<language code>"}' \\ 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 { "user id" "unique user id" } or { "chat id" "id of the chat requesting handover" } 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 https //docs v2 kindly ai/application api#iy new application 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", "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 { "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 {} you can also write to context when sending a message or triggering a greeting examples curl h 'content type application/json' \\ h "authorization bearer your api key" \\ d '{"user id" "unique user id", "message" "hello world!", "language code" "en", "new context" { "purchase flow complete" true }}' \\ 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", "new context" { "purchase flow complete" true }}' \\ https //bot kindly ai/api/v1/greet 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 { &#x9;"user id" "\<unique user id>", &#x9;"submission id" "\<form submission id>", &#x9;"context" { &#x9; "\<slug field>" "\<selected slug>" &#x9;}, &#x9;"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 { &#x9;"form submission id" "\<form submission id>", &#x9;"form id" "\<form id>", &#x9;"state" "\<form state>", &#x9;"updated context" { &#x9; " name" "\<api name>", &#x9; " organization name" "\<org name>", &#x9; "\<slug field>" "\<selected slug>" &#x9;} } privacy deleting all chats for user you can delete all chats for a specific user by making a delete request to https //bot kindly ai/api/v1/privacy/delete the post payload should be in the following format { "user id" "\<unique user id>" } upon successful submission, the response will be structured as follows \[ { "deletedmessages" \<quantity of deleted messages>, "deletedformsubmissions" \<quantity of deleted form submissions>, "deletedchat" "\<id of the chat>" }, { } ] example curl h 'content type application/json' \\ h "authorization bearer your api key" \\ d '{"user id" "unique user id"}' \\ x delete \\ https //bot kindly ai/api/v1/privacy/delete 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