Install the chat

1. 01

   Allow your site

   On the Install tab, add every site the chat will appear on under Allowed origins. Until you add one, the widget is blocked everywhere.

2. 02

   Copy the snippet

   Choose HTML, Next.js / React or WordPress, Shopify, Webflow and copy the code.

3. 03

   Paste it before </body>

   On every page where the chat should appear. WordPress: a header and footer plugin. Shopify: theme.liquid before </body>. Webflow: Site settings, Custom code, Footer.

4. 04

   Open your site

   The launcher appears in the corner. If it does not, open the browser console: a message says which origin is missing.

<script src="https://cdn.kothadesk.com/widget/v1/widget.js"
  data-bot-id="bot_your_bot_id"
  data-api-url="https://api.kothadesk.com"
  async></script>

Copy the snippet from your Install tab rather than this example: it has your bot id and the right addresses.

• Enter the scheme and host, with an optional port and no path: https://www.example.com.
• https://*.example.com allows one level of subdomain (shop.example.com), but not example.com itself: add that separately.
• http is accepted only for localhost while you test.
• Up to 50 origins per bot.

From your page's JavaScript you can call Kothadesk.open(), close(), toggle(), identify(), setContext(), reset() and destroy(), and listen to events such as ready, open, close, message:sent, message:received, citation:click and feedback with Kothadesk.on().

document.querySelector("#help").addEventListener("click", () => {
  Kothadesk.open({ message: "I need help with my order" });
});
Kothadesk.on("message:received", () => console.log("The assistant replied"));

If your site sends a CSP header, allow the sources shown on your Install tab: the widget's CDN in script-src, the API and CDN in connect-src, and the API and CDN in img-src (the API serves the avatar and launcher icon you upload on the Appearance tab; add the file storage origin if you turned on attachments, and the host of any image URL you pasted instead of uploading).

• Using the human check (Turnstile): add https://challenges.cloudflare.com to script-src and frame-src.
• Using voice calls: serve the site over HTTPS and allow the microphone (Permissions-Policy: microphone=(self)).
• The widget needs no unsafe-eval and uses no iframe of its own.

When your visitors are logged in to your site, you can tell the assistant who they are with a signed identity token. It unlocks their conversations across devices, names in the inbox, memory, tools that act on their account and routing by plan or region.

1. 01

   Generate the secret

   On the Install tab, Identity verification, generate the workspace secret (idsec_...). It is shown once; keep it on your server. After a rotation the old secret works for 24 more hours.

2. 02

   Sign a token on your server

   HS256, with sub (your user id) and exp (at most 10 minutes ahead). Optional: name, email and ctx, a small JSON object with trusted details such as plan.

3. 03

   Give the widget a function that fetches it

   The widget calls it whenever it needs a fresh token.

4. 04

   Choose the mode

   Signed-in visitors: Optional lets anyone chat and recognises signed-in users; Required allows only signed-in users.

import jwt from "jsonwebtoken";

app.get("/chat-token", requireLogin, (req, res) => {
  const token = jwt.sign(
    { sub: req.user.id, name: req.user.name, email: req.user.email, ctx: { plan: req.user.plan } },
    process.env.KOTHADESK_IDENTITY_SECRET,
    { algorithm: "HS256", expiresIn: "10m" },
  );
  res.json({ token });
});

Kothadesk("init", {
  identityToken: async () => (await fetch("/chat-token").then((r) => r.json())).token,
});

Watch out: Never sign tokens in the browser and never put the secret in your page. Anyone with the secret could pretend to be any of your users.

No website, or want a link for WhatsApp, email or a printed QR code? Turn on the hosted chat page on the Install tab. It uses your bot's title, colours and avatar.

• Custom link: 3 to 48 lower-case letters, digits and single hyphens, for example yourclinic-help.
• Copy the link or download the QR code.
• Search engines are told not to index it unless you tick Let search engines index this page.

For your own web app or a mobile app, use the SDKs from the Developers page (they are not on npm or pub.dev; download them from the SDK kit).

npm install ./vendor/kothadesk-sdk-js-0.4.0.tgz

import { ChatClient } from "@kothadesk/sdk-js";
const client = new ChatClient({ botId: "bot_your_bot_id", apiUrl: "https://api.kothadesk.com" });

Flutter: add the SDK from the kit as a path dependency, create a KothadeskClient with your bot id, API address and the publishable key from the Mobile apps card, then create a KothadeskController and show it full screen with KothadeskView or as a floating button with KothadeskLauncher. See the Developers page for the full steps.