Installare il widget

Installare Webble richiede due pezzi: un piccolo endpoint per il token sul tuo backend e un tag script nelle tue pagine. La finestra Installa widget della dashboard li genera entrambi con i valori del tuo sito già compilati. Questa pagina spiega cosa fanno — scegli il tuo stack nelle schede qui sotto.

Perché un endpoint per il token?

Il widget non porta mai un segreto nel browser. Il tuo backend custodisce un API token di Webble e lo scambia con token di chat a breve scadenza, limitati al tuo sito. Il widget interroga il tuo endpoint e usa ciò che restituisce. Un token di chat trapelato scade da solo, e revocare l'API token ferma lo scambio.

1. Crea un API token

Crea un API token per il tuo sito nella dashboard e conservalo tra i segreti del backend come WEBBLE_API_TOKEN. Non deve mai comparire nel codice lato client.

2. Aggiungi l'endpoint del token

Il tuo endpoint inoltra lo scambio a Webble e restituisce la risposta così com'è — codice di stato compreso, perché il widget interpreta un 403 (modalità test, tetto di spesa) come "nasconditi". Marca la risposta Cache-Control: no-store, altrimenti una risposta in cache continua a servire un token ormai scaduto.

Sostituisci ID_DEL_TUO_SITO con l'id del tuo sito, mostrato nella 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: "ID_DEL_TUO_SITO" }),
    cache: "no-store",
  });
  return Response.json(await res.json(), {
    status: res.status,
    headers: { "cache-control": "no-store" },
  });
}

3. Aggiungi il tag script

data-wb-token-url punta all'endpoint del punto 2, sulla tua stessa origine.

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

• data-wb-site è l'id del tuo sito, mostrato nella dashboard.
• data-wb-token-url è l'endpoint del punto 2, sulla tua stessa origine.
• data-wb-lang è opzionale. Forza la lingua del widget invece di seguire il browser del visitatore.

Il widget viene renderizzato in uno Shadow DOM, quindi il CSS del tuo sito e quello del widget non si toccano mai. Colori, stile del launcher e messaggio introduttivo si configurano per sito nello studio dell'aspetto della dashboard.

Modalità test e live

Finché il sito è in modalità test, lo scambio del token rifiuta i widget installati, e solo l'anteprima della dashboard può chattare. Porta il sito in modalità live quando sei pronto per i visitatori.