Chat API

Kindly Chat is a feature rich and customizable chat client for the web. New versions packing features and updates are made available continously. You can read more on supported versions below.

Get the HTML snippet

Start by navigating to your bot in the Kindly platform.

Select Connect from the left-hand menu, then click Kindly Chat - Publish your chatbot.

Under the heading Get HTML code go ahead and copy it by hitting Copy to clipboard. You'll need this code to embed Kindly Chat on your site.

The HTML snippet should look something like this:

<script
	id="kindly-chat"
	src="https://chat.kindlycdn.com/kindly-chat.js"
	data-bot-key="YOUR-BOT-KEY"
	data-shadow-dom="1"
	async
></script>

A pure build is also available.

Deploying Kindly Chat

Once you have copied the snippet, you're ready to add Kindly Chat to your site. This should be a simple process that involves updating an HTML template. Put the snippet in your HTML template, before the closing </body> tag.

If this sounds strange, foreign or scary, we recommend you contact your website administrator or a developer in your organization for further assistance.

Using Google Tag Manager?

When using Google Tag Manager (GTM), the script needs to be added programmatically. This means the HTML snippet won't work, as GTM won't be able to load its attributes like data-bot-key. When adding a new tag, choose the "custom HTML" option and paste the following snippet into the editor:

<script>
	var script = document.createElement("script");
	script.src = "https://chat.kindlycdn.com/kindly-chat.js";
	script.async = true;
	script.id = "kindly-chat";
	script.setAttribute("data-shadow-dom", "1");
	script.setAttribute("data-bot-key", "YOUR-BOT-KEY");
	document.body.appendChild(script);
</script>

One thing worth noting when implementing with GTM, is that the chat bubble can be hidden for some users using an ad blocker extension. Therefore we do recommend implementing the chat bubble directly into the source code, or via a CMS if possible.

Customizing

There are two options available for configuring Kindly Chat appearance and behaviour:

Set default settings directly through the Kindly platform.
Override the default settings using options in your site HTML (window.kindlyOptions). This allows for per page customization. See the section options reference for a list of supported options.

Set default behaviour and appearance

Start by navigating to your bot in the Kindly platform.

From the left-hand menu, open Settings, then go to Kindly Chat.

Configure the bot behaviour and appearance according to your needs.

Override behaviour or appearance per page

Sometimes Kindly Chat needs slightly different behaviour or appearance depending on the page the user is visiting. This can be accomplished by adding options to the original HTML snippet. Use the following HTML snippet for overriding the settings. Remember to replace the part that says 'YOUR-BOT-KEY' with the value from your original HTML snippet.

NOTE: In this example, available options have been commented out. To activate an option, uncomment the line by removing "//" from the start of the line.

<script>
	window.kindlyOptions = {
		// chatbubble: {
		//   autopopup: false,
		//   autopopup_time: 10000, // ms
		// },
		// name: 'Your bot name',
		// bubbleHidden: true,
		// context: { /* your own context */ },
		// getAuthToken: async function(chatId) { /* return token code */ },
	};
</script>
<script
	id="kindly-chat"
	src="https://chat.kindlycdn.com/kindly-chat.js"
	data-bot-key="YOUR-BOT-KEY"
	async
></script>

Set initial language

If you need to pre-configure which language the bot should use to greet the user, just set window.kindlyOptions.language to a valid language code. See example below.

<script>
	window.kindlyOptions = {
		language: "nb",
	};
</script>
<script
	id="kindly-chat"
	src="https://chat.kindlycdn.com/kindly-chat.js"
	data-bot-key="YOUR-BOT-KEY"
	async
></script>

Valid language codes

The currently supported languages and codes are listed on the languages page.

Options reference

Options are passed in with data attributes on the <script> tag or the global window.kindlyOptions.

Property reference

Property, type

Data attribute

Default

Description

bubbleHidden bool

data-bubble-hidden

false

Hides the bubble initially

chatbubble.autopopup bool

Automatically popup chat window

chatbubble.autopopup_time number

Milliseconds to wait before popup of chat window

context object

undefined

Initial chat memory / context.

fullscreenMode bool

Makes the chat window take up the entire screen

hideHeader bool

hides the header component of the chat window

language string,

data-language

Initial bot and interface language

position.bottom string,

20px

Offset position of the chat icon, relative to bottom of window.

position.right string,

20px

Offset position of the chat icon, relative to right of window. Keep in mind that elements will keep their place relative to the chat icon, and that elements will always appear to the left.

shadowDom

data-shadow-dom

false

Render Kindly Chat HTML in a

styles

data-styles

""

NB: Use at own risk, we do not guarantee stable class names. CSS injected into Shadow DOM to override styles.

zIndex number

5000

Control the z-index of the chat container if it's hidden behind other elements

bubbleAvatar

""

Accepts a single string, which should be the location for the image file. The image will be displayed inside the bubble.

Event reference

You can attach event listeners for the following events emitted by the kindly chat client.

event

event.detail

Description

kindly:load

{settings}

Triggered once after Kindly Chat has loaded server side settings. It receives the complete settings object. Functions like openChat and closeChat should be called after this.

kindly:message

{newMessage, chatLog}

Triggered on every message, including user, agent and system messages. It receives the last message and complete chat log.

kindly:buttonclick

{button, buttonType, lastMessage, chatLog}

Triggered on every button click. It receives the button details, button type, last message and complete chat log. To prevent running the default actions of that button type, you can call event.preventDefault() on the DOM event in the event listener.

Examples

document.addEventListener('kindly:load', (event) => {
  console.log('💖💖', event.detail);

  if(Math.random() >= 0.5) {
    kindlyChat.showBubble();
  }
});

window.addEventListener('kindly:buttonclick', (event) => {
  console.log('This is the event payload:', event.detail);
  
  const buttonData = event.detail.button;

  trackGoogleAnalytics(buttonData);
});

Note: Using events instead of callbacks is encouraged and all equivalent callback style APIs are deprecated.

Callback reference (deprecated)

Property and callback signature

Description

onLoad: () => {}

Deprecated: use kindly:load event listener instead. onLoad is called once after Kindly Chat has loaded server side settings. Functions like openChat and closeChat should be called inside this callback

onMessage: (newMessage, chatLog) => {}

Deprecated: use kindly:message event listener instead. onMessage is called on every message, including user, agent and system messages. It receives the last message and complete chat log

buttonHandlers: {[BUTTON_TYPE]: (event, button, lastMessage, chatLog) => {}}

Deprecated: use kindly:buttonclick event listener instead. Each type of button takes a callback and buttonHandlers[BUTTON_TYPE] is called on click for that BUTTON_TYPE. It receives the DOM event, button definition, last message and complete chat log. Valid BUTTON_TYPE's are quick_reply, takeover_request, link, email, phone, dialogue_trigger, privacy_export, privacy_delete. If you return true from a button handler the default actions of that button type are not run (similar to event.preventDefault()).

getAuthToken: (chatId) => {}

getAuthToken is called once the chat is started to authenticate the user. It must return a signed JWT token.

Nudge callbacks

Callback used along with nudges. Read more about them here.

Function

Supported nudge types

Description

onNudgeDismiss: () => { ... },

All

onNudgeDismiss is triggered whenever a nudge is closed.

onNudgeFormSubmit: (e, values) => { ... },

Form nudge

onNudgeFormSubmit is triggered whenever a form nudge is submitted. It contains the submit event along with the input value.

onNudgeProductClick: (e, product) => { ... },

Product nudge

onNudgeProductClick is triggered when a specific product on a product nudge is clicked. However, it is only triggered if linkUrl is not sent as a property in the items array

Function reference

Available methods on window.kindlyChat

Function

Description

showBubble()

Shows the bubble icon, which affects bubbleHidden

hideBubble()

Hides the bubble icon, which affects bubbleHidden

openChat()

Opens the chat window

closeChat()

Closes the chat window

showNudge({ nudgeLayout })

Trigger selected dialogue in chat, using ID or slug. options is an optional object. It may include languageCode to specify language and openChat to open the chat window.

showCustomNudge({ content })

Trigger selected dialogue in chat, using ID or slug. options is an optional object. It may include languageCode to specify language and openChat to open the chat window.

triggerDialogue("[DIALOGUE_ID]", options)

Trigger selected dialogue in chat, using ID or slug. options is an optional object. It may include languageCode to specify language and openChat to open the chat window.

identifyUser(identity)

Add a user identity to the the current chat session. Read more about .

Nudge functions

The following functions are usable independant of the nudge type you want to use them with. Read more about nudges here.

Function

Description

showNudge({ slug: 'string', nudgeLayout: object });

showNudge is used to trigger a specific nudge, either from the platform or from a given layout.

closeNudge();

closeNudge will close any active nudge. If no ones open, the function won't do anything.

Authentication

Kindly supports authenticating your users. When your users are authenticated, it's easier to identify them in the Kindly Inbox and you can create more personalized and powerful webhook integrations.

To set this up you need to do a few things:

Add a callback to Kindly Chat initialization code.
Create a private/public key pair.
Create an authentication endpoint that returns a JWT in a specific format.

After the inital implementation and setup you are able to:

See user details in the Kindly Inbox.
Identify users in webhooks (via the forwarded JWT).

Read more about authenticating your users in the full Kindly Chat authentication guide.

Supported versions

Major versions are released on a six month cycle and there will be no breaking changes outside of a major release.

We provide support for the latest two major versions.

We follow semantic versioning when naming versions of Kindly Chat.

Pure build

We also provide a special JavaScript build that does not pollute the global scope (window) to prevent possible conflicts with existing code. The script tag is almost identical to the main build, except the URL ends in -pure.js:

<script
	id="kindly-chat"
	src="https://chat.kindlycdn.com/kindly-chat-pure.js"
	data-bot-key="YOUR-BOT-KEY"
	data-shadow-dom="1"
	async
></script>

The side effect of this is that it does not add polyfills to support older browsers. This means you need to add the necessary polyfills to your own browser environment, to maintain support. This can be done using polyfill.io. The current polyfills we use in the main build, to allow Internet Explorer 11 (IE11) users to be happy, are:

import "core-js/features/weak-set";
import "core-js/features/promise";
import "core-js/features/object/values";
import "core-js/features/object/assign";
import "core-js/features/object/entries";
import "core-js/features/array/find";
import "core-js/features/array/find-index";
import "core-js/features/array/from";
import "core-js/features/string/starts-with";
import "core-js/features/symbol/iterator";
import "intersection-observer";
import "./polyfillCustomEvent"; // From https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#polyfill

PreviousApplication API NextChat Log API

Last updated 2 years ago