Add the chat widget to your website

The Wassla web widget puts an AI agent on any website using a single script tag. Create a widget key in Settings → Widget keys, list the domains it is allowed to run on, paste the snippet just before the closing </body> tag, and the chat bubble appears in the corner. The widget loads asynchronously inside a Shadow DOM, so it never blocks page paint and your site's CSS cannot leak into it.

Step 1: Create a widget key

A widget key is the public credential the embed snippet uses to authenticate with Wassla. Each key has its own allowed-origins list, so you can use one key per site (recommended) or share a key across staging and production by listing both domains.

1. Open the workspace dashboard and go to Settings → Widget keys.
2. Click New widget key.
3. Give the key a memorable name (for example, Marketing site or Help center).
4. In Allowed origins, paste one origin per line. Use the full scheme and host with no trailing slash, for example:
   • https://example.com
   • https://www.example.com
   • https://app.example.com
5. Click Create.

The key starts with the wpk_ prefix and is shown immediately in a snippet viewer. You can come back to Settings → Widget keys at any time, click the code icon next to a key, and copy the snippet again — the key itself is safe to ship in client-side HTML.

Allowed origins are enforced default-deny on the server. A request from a domain that is not on the list is rejected with HTTP 403 before the AI is ever called, which protects your credit balance if the key is copied to a site you do not control. A key with an empty origins list is effectively disabled, and the table flags it with a "No origins — widget disabled" warning.

Step 2: Paste the snippet into your site

The snippet is two <script> tags. The first loads widget.js from your Wassla workspace URL; the second initializes the widget with your public key.

1. In the snippet viewer, click Copy.
2. Paste the snippet into your site's HTML, just before the closing </body> tag, on every page where you want the widget to appear.
3. Deploy your site and open it in a fresh browser tab.

A purple chat bubble appears in the bottom corner. Click it to open the panel, type a message, and confirm the AI agent answers.

The default snippet looks like this:

<script src="https://wassla.io/widget.js" defer></script>
<script>
  window.addEventListener('load', function () {
    Wassla.init({ publicKey: "wpk_..." });
  });
</script>

If you use a tag manager (Google Tag Manager, Segment, Shopify script tag, etc.), paste both scripts into a single custom HTML tag that fires on All pages. The defer attribute means the widget never blocks first paint.

Step 3: Customize the look and welcome message

The Wassla.init call accepts a few options that change the widget's appearance and copy without redeploying anything on Wassla's side — just edit the snippet on your site.

A fully customized snippet looks like this:

<script src="https://wassla.io/widget.js" defer></script>
<script>
  window.addEventListener('load', function () {
    Wassla.init({
      publicKey: "wpk_...",
      accent: "#0f766e",
      title: "Talk to our team",
      greeting: "Hi! Ask us anything about pricing or shipping."
    });
  });
</script>

The widget is right-to-left aware: if your page sets dir="rtl", the bubble and panel mirror to the start side automatically because the embedded CSS uses logical properties (inset-inline-end rather than right).

Step 4: Set the default agent

Each widget key answers with one agent. By default a key has no agent assigned and falls back to the first active agent in your workspace, which is fine if you only run one agent. If you have more than one agent (for example, Sales #support and Operations #support), you should bind each widget key to a specific agent so visitors on your pricing page get the sales agent and visitors on your help center get the operations agent.

1. Open Settings → Agents and confirm the agent you want is active.
2. Go to Settings → Widget keys and create a separate key for each site or page where the agent should answer.
3. Today, agent binding on a widget key is set via the API (the agent_id column on tenant_widget_keys); the default-agent dropdown in the Widget keys modal ships in the next Settings update. If you need to bind an agent right now, contact support and we will set it on the key for you.

You can preview how each agent sounds before pointing a widget at it — see Train your AI agent and Tune your agent's personality.

Step 5: Configure visitor identification

The widget streams replies anonymously by default — every visitor is a fresh conversation tied to a browser tab. Conversation continuity within a tab is handled automatically: the widget captures a conversationId from the first server-sent event and resends it with every follow-up so the agent has memory inside the same session.

If you want the agent to greet logged-in users by name, attach the customer to a CRM record, or hand off to a human with the visitor's email, you have two options today:

• Pre-fill the greeting from your site: read the logged-in user's name from your app and pass it into the greeting option, for example greeting: "Hi Sara, how can we help today?". This is the simplest path and works on any plan.
• Send identified payloads to a webhook: forward conversation transcripts to your own backend with the visitor's identifiers using the conversations webhook. See Channel troubleshooting for the event shape and verification headers.

A first-class Wassla.identify({ name, email, externalId }) API that signs the visitor identity end-to-end is on the roadmap and is not shipped yet — do not pass identifiers as plain URL parameters, since they are visible to anyone who views the page source.

Verify the widget is working

Open the page in a new browser tab (not the one you have the dashboard in, to be sure you are not using a logged-in session). You should see:

1. The chat bubble appears in the bottom corner within a second of the page loading.
2. Clicking the bubble opens a panel with your title and greeting.
3. Sending a message shows a typing indicator, then a streaming reply from your agent.
4. Refreshing the page and opening the panel starts a new conversation — that is expected.

If the bubble does not appear, open the browser console. A missing key logs [Wassla] init: publicKey is required. If you see a 403 in the Network tab against /functions/v1/widget, the page's origin is not in the key's Allowed origins list — go back to Step 1 and add it (remember: no trailing slash, exact scheme and host match). If you see a 429, the key has hit its per-minute rate limit (30 requests per minute by default); contact support to raise it.

Related articles

• Tune your agent's personality
• Train agents with a knowledge base
• Channel troubleshooting