Installing the widget

Installing Webble takes two pieces: a small token endpoint on your backend and a script tag on your pages. The dashboard's Install widget dialog generates both with your site's values already filled in. This page explains what they do — pick your stack in the tabs below.

Why a token endpoint?

The widget never ships a secret to the browser. Your backend holds a Webble API token and exchanges it for short-lived chat tokens scoped to your website. The widget polls your endpoint and uses whatever it returns. A leaked chat token expires on its own, and revoking the API token stops the exchange.

1. Create an API token

Create an API token for your website in the dashboard and store it in your backend's secrets as WEBBLE_API_TOKEN. It must never appear in client-side code.

2. Add the token endpoint

Your endpoint forwards the exchange to Webble and returns the response unchanged — status code included, because the widget reads a 403 (test mode, spend cap) as "hide yourself". Mark the response Cache-Control: no-store, otherwise a cached response keeps serving a token that has already expired.

Replace YOUR_SITE_ID with your website's id, shown in the dashboard.

export async function GET() {
  const res = await fetch("https://webble.it/api/v1/widget-tokens", {
    method: "POST",
    headers: {
      authorization: `Bearer ${process.env.WEBBLE_API_TOKEN}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({ websiteId: "YOUR_SITE_ID" }),
    cache: "no-store",
  });
  return Response.json(await res.json(), {
    status: res.status,
    headers: { "cache-control": "no-store" },
  });
}

3. Add the script tag

data-wb-token-url points at the endpoint from step 2, on your own origin.

<script
  src="https://webble.it/widget/webble.iife.js"
  data-wb-site="YOUR_SITE_ID"
  data-wb-token-url="/api/webble-token"
></script>

• data-wb-site is your website's id, shown in the dashboard.
• data-wb-token-url is the endpoint from step 2, on your own origin.
• data-wb-lang is optional. It forces the widget's language instead of following the visitor's browser.

The widget renders in a Shadow DOM, so your site's CSS and the widget's never touch. Colors, launcher style and the intro message are configured per website in the dashboard's appearance studio.

Test mode vs live

While your website is in test mode, the token exchange refuses deployed widgets, and only the dashboard preview can chat. Switch the website to live mode when you're ready for visitors.