APIs

Chat Widget API

the chat api enables you to interact with the kindly chat embedded on your website kindly chat is a feature rich and customizable chat client for the web new versions packing features and updates are made available continuously you can read more on supported versions https //docs kindly ai/api/chat#m 9r 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 a pure build https //docs kindly ai/api/chat#e2tal 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, between the \<head> or \<body> tags 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 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 https //docs kindly ai/api/chat#ii4st 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 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 languages docid\ jtm5dxgyrj99xvjkxgkdv the language must have been activated in the kindly platform before see example below chat options window\ kindlyoptions you can control your kindly chat settings by setting some options through the global window\ kindlyoptions or with the data attributes on the kindly chat \<script> tag property reference property , type data attribute default description bubbleavatar string "" accepts a single string, which should be the location for the image file the image will be displayed inside the bubble 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 customfont set a different font family, for example window\ kindlyoptions = { customfont '"comic sans ms", cursive, sans serif' } focustraponfullview bool false if true , this option activates a focus trap when the chat covers the entire screen this ensures that keyboard and screen reader navigation remains within the chat interface, improving accessibility for users relying on voiceover and keyboard controls this setting may default to true in future updates, but for now, it must be explicitly enabled 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 chat properties window\ kindlychat kindly chat comes with some useful methods and data properties property reference property description isbrowsercompatible bool whether kindly chat officially supports the current browser or not open bool if true, it means the chat window is open 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 restartchat(options) restarts the chat options object openchat boolean if true, it will open/keep open the chatbubble cancelhandover() it terminates the ongoing handover, whether the user is in the queue or already engaged in the process sendmessage(message, options) send a message into the chat message string the message to send in the chat options object sender "user" who to make as a sender of the message required field newcontext? record\<string,string> context keys and values to attach to the chat openchat? boolean if true, it will open the chat if it was closed default is true 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({ full name "john doe" }) add a user identity to the current chat session allowed fields , user id , avatar url , full name , email and phone number async getcontext() get the current chat context setnewcontext({"key" "value"}) add some additional context to the current conversation the context can e g be used in webhooks or by bot builders setnewlabel("newlabel") add an additional label to the current conversation if the chat hasn't started yet when you invoke this function, an empty labelled chat will be created in insights, without the customer knowing it setnewbannermessage({content "banner message text here", buttonhref "https //example com", buttontext "example"}, "23234") the last parameter is an id it is optional, and is used to make sure the same banner message is not shown twice to the same user nudge property reference you also have some properties to handle nudges these are usable independently of the nudge type you want to use them with read more about nudges here https //docs kindly ai/api/nudge property description shownudge({ slug 'string', nudgelayout }); shownudge is used to trigger a specific nudge, either from the platform or from a given layout showcustomnudge({ content, slug, onrendered, onrendered }) showcustomnudge is used to trigger a nudge with a fully custom layout closenudge(); closenudge will close any active nudge if there is no one open, the function won't do anything examples displaying the chat bubble only if the browser is officially supported keep in my mind that kindly chat could still work fine for more browsers than the officially supported ones, so we suggest the approach below only if really necessary send a message in kindly chat on behalf of the user this could be useful, for example, if you have a support form on your website before submitting the customer's inquiry to your backend, you could ask directly in the chat and only if the chat goes to fallback then submit it to your backend or an agent window\ kindlychat sendmessage("hi, do you sell computers as well?", {sender "user"}) chat events you can attach event listeners for the following events emitted by the kindly chat client event reference event event detail description kindly\ load settings object 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 object chatlog object triggered on every message, including user, agent and system messages it receives the last message and the complete chat transcript kindly\ buttonclick button object buttontype string chatlog object lastmessage object triggered on every button click it receives the button details , button type , last message and the complete chat transcript to prevent running the default actions of that button type, you can call event preventdefault() on the dom event in the event listener kindly\ ui type string source 'user' | 'programmatic' chatid string value? object feedbacktype 'rating scale' | 'predefined buttons' | 'freeform text' | 'thank you' feedbackvalue { language code string; rating system number; trigger type 'bot conversation' | 'handover conversation'; index number; rating string; sentiment 'negative' | 'neutral' | 'positive'; buttons chosen string\[]; freeform text string | null; } or languagecode string languagename string previouslanguagecode string previouslanguagename string or nextpage welcome page / chat triggered when some actions are performed in kindly chat the type property will say which particular action was performed currently, we support open chatbubble close chatbubble end chat restart chat download chat delete chat change language show feedback submit feedback dismiss feedback welcome page start chat the source property will say if the action was somehow initiated by the user or not the chatid is provided as well, when available in the event triggered the value property will carry any meaningful info (if any) in relation to the action performed currently, we expose a value for feedback , language and open chatbubble events kindly\ globalicon type string icon? object id string title string alttext? string imageurl? string type 'url' | 'dialogue' | 'nudge' action string triggered when certain actions are performed in relation to global icons the type property indicates which particular action was performed currently, we support only trigger globalicon the icon action corresponds to the action the icon will trigger it can be a url, a dialogue slug/id, or a nudge slug nudge callbacks these are callbacks used along with nudges nudge api docid\ dhqt3vmsp8gu6k2 ckp3p we don't have yet an event emitter api for these events so it's currently working with callbacks that you can set on window\ kindlyoptions 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 examples logging the payload and randomly displaying the chat bubble on kindly\ load document addeventlistener('kindly\ load', (event) => { console log('💖💖', event detail); if(math random() >= 0 5) { kindlychat showbubble(); } }); logging and sending to analytics the button data on kindly\ buttonclick window\ addeventlistener('kindly\ buttonclick', (event) => { console log('this is the event payload ', event detail); const buttondata = event detail button; trackgoogleanalytics(buttondata); }); tracking every time the user manually switches language window\ addeventlistener(`kindly\ ui`, (event) => { const { detail } = event; const eventtype = detail type; // in general, for tracking user behaviour, it's good practice to also // check that `source` is `user`, since perhaps you wouldn't want to track // if the action was somehow initiated/performed by the chat itself if (eventtype === 'change language' && detail source === 'user') { const payload = { incrementcount eventtype, targetlanguage detail value languagename } sendtogoogleanalytics(payload) } } ⚰️ 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 the complete chat transcript 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 the complete chat transcript 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 authentication kindly supports authenticating your users when your users are authenticated, it's easier to identify them in the kindly insights 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 https //jwt io/ in a specific format after the initial implementation and setup, you are able to see user details in kindly insights identify users in webhooks (via the forwarded jwt) read more about authenticating your users in the full kindly chat authentication docid\ edoiixeuyfxeny4tqylpf supported versions major versions are released on a six month cycle and there will be no breaking changes outside of a major release we follow semantic versioning when naming versions of kindly chat browser support for kindly chat widget is based on the following logic >0 2% in alt eu we support browsers that have more than 0 2% of the market share in europe (alternative data source) >0 2% in us we support browsers that have more than 0 2% of the market share in the united states last 3 years we support all browsers that have been released in the last 4 years not dead we do not support browsers that are no longer maintained not operamini all we do not support any versions of opera mini not edge < 20 we do not support microsoft edge versions older than version 20 not opera < 63 we do not support opera versions older than version 63 not safari < 13 we do not support safari versions older than version 13

Application API

Chat Transcript API