Skip to main content

Web Widget

The fastest way to put your assistant in front of users: a chat widget on your website. Visitors click the launcher, ask a question, and your agent answers from your knowledge. Setup is one script tag.

Find it in your application: open Channels, then Widget.

Step 1: Turn it on​

  1. Flip Enabled. This activates the widget endpoint so it accepts chat requests.
  2. Decide who can chat with Allow anonymous visitors:
    • On: any visitor can chat. Docana creates guest users as needed. Right for public websites.
    • Off: only existing Docana users with access to this application can chat. Right for internal portals. This mode requires the identity secret from Verify visitor identity: without it the widget cannot tell which member is chatting, and the settings page refuses to save it.
Enable the widget and decide whether anonymous visitors and attachments are allowed.
Enable the widget and decide whether anonymous visitors and attachments are allowed.

Step 2: Lock it to your domains​

In Allowed origins, list the sites that may embed the widget, one per line. Wildcard subdomains like *.example.com work. Leaving it empty allows any origin, which is fine for testing and a bad idea in production.

Step 3: Create an API key​

The widget authenticates every request with a Docana API key. Create one with the Widget only scope, which can only call the widget's chat, history, and archive endpoints. See Generating API Keys.

Step 4: Embed it​

The widget settings include a playground where you customize the look (title, welcome message, color, position, launcher) and watch the embed snippet update live. Copy it and paste it into your site before the closing </body> tag:

<script src="https://platform.docana.com/widget/v1.js" defer></script>
<script>
  window.addEventListener("load", function () {
    DocanaWidget.init({
      applicationId: 1234567890123,
      apiKey: "your_widget_api_key_here",
      baseUrl: "https://platform.docana.com",
      title: "Support",
      welcomeMessage: "Hi! How can we help?",
      primaryColor: "#3182ce",
      position: "bottom-right"
    });
  });
</script>

That's the whole integration. Reload your site and the launcher appears.

The widget playground lets you set the title, greeting, and other embed options before loading a preview.
The widget playground lets you set the title, greeting, and other embed options before loading a preview.

Optional: Verify visitor identity​

If your site has logged-in users, you can prevent impersonation. Turn on Visitor identity verification, generate the identity secret, and store it on your server. Never put it in client-side code. The secret is optional for a public widget and required when Allow anonymous visitors is off, because a signed visitor ID and email are the only way the widget can match a chat to a Docana member.

Your server signs each visitor's ID with HMAC SHA-256 using the secret, and you pass the result to the widget as hash. If you also want Docana to match the visitor to a member by email, sign the ID and the email together as emailHash: the ID, a newline, then the email trimmed and lowercased.

// On your server
const crypto = require("crypto");
const sign = (payload) =>
  crypto.createHmac("sha256", process.env.DOCANA_IDENTITY_SECRET).update(payload).digest("hex");

const email = "[email protected]".trim().toLowerCase();
const hash = sign("user-123");
const emailHash = sign(`user-123\n${email}`);
// On your page
DocanaWidget.init({
  // ...
  visitor: {
    id: "user-123",
    email: "[email protected]",
    name: "Alice",
    hash: "hmac_sha256_of_the_id",
    emailHash: "hmac_sha256_of_the_id_and_email"
  }
});

With verification on, Docana rejects any visitor whose hash doesn't match. An email without a matching emailHash is ignored, so the visitor chats under their own ID and can't be matched to anyone else's account. Without the secret, nobody can pretend to be Alice.

Other settings​

  • Agent routing: send widget conversations to a specific agent, or let the application's default assistant handle everything
  • Attachments: let visitors send files and paste images from the clipboard
  • Voice and language: pick the voice for spoken replies and bias the response language
  • Sounds: toggle notification sounds for open, send, and receive

Calling the API directly​

The widget is a UI over a plain HTTP endpoint. If you'd rather build your own chat interface, call the endpoint from your backend with the same API key. The widget settings page shows a ready-to-run curl example, and the API Overview covers the details.

Next steps​