> ## Documentation Index > Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt > Use this file to discover all available pages before exploring further. # Instale o Widget para Site > Guia de instalação direta para desenvolvedores — uma tag de script, receitas por framework, referência do SDK, identidade assinada de visitante, notas de CSP, checklist de verificação e um prompt pronto para copiar para agentes de programação com IA. Este guia é para o desenvolvedor que vai incorporar o widget de chat do Switchbord em um site. A instalação é uma única tag de script assíncrona; todo o resto desta página é aprofundamento opcional — receitas para SPAs, o SDK JavaScript, identidade assinada para usuários autenticados e resolução de problemas. ## Pré-requisitos Do operador do workspace (ou de **Settings → Integrations → Channels → Website widget**, se for você): * O **snippet de instalação** (ou apenas o **slug** do widget e a URL base da API). * Confirmação de que a origem do seu site está na lista de **origens permitidas** do widget — o esquema + host exatos, p. ex. `https://www.example.com`. `www` e o domínio raiz são origens diferentes; adicione ambos se ambos servirem o site. A base da API hospedada é `https://api.switchbord.ai`. Instâncias self-hosted substituem seu próprio domínio de API em todos os lugares em que ele aparece abaixo. ## O snippet Cole isto antes da tag de fechamento `` em cada página que deve exibir o widget: ```html theme={null} ``` Essa é a instalação inteira. O script injeta uma bolha de abertura e um iframe isolado; aparência, textos e comportamento de IA são todos controlados em Settings do Switchbord e publicados sem mudanças no snippet. Se você quiser chamar o SDK antes de o script ter carregado (por exemplo `setVisitor` em código inline), adicione primeiro o stub de fila de comandos — chamadas feitas antes do carregamento são enfileiradas e reexecutadas: ```html theme={null} ``` ## Receitas por framework Cole o snippet antes de `` no seu layout/template base para que ele apareça em todas as páginas. Pronto. Use `next/script` no layout raiz para que o widget carregue uma vez por sessão de navegação, apenas no cliente: ```tsx theme={null} // app/layout.tsx import Script from "next/script"; export default function RootLayout({ children }) { return ( {children} ``` ## Identidade assinada (Secure Mode) Se o seu site tem usuários autenticados, emita um JWT HS256 de curta duração no **seu servidor** e passe-o para `login()` para que o Switchbord saiba de forma verificável quem é o visitante. Visitantes verificados retomam a conversa entre dispositivos, e os operadores veem dados de contato verificados em vez de sessões anônimas. Configuração: 1. No Switchbord, gere o **segredo de assinatura de identidade do widget** em **Settings → Integrations → Provider secrets** (`widget-identity-secret`). Ele é armazenado no Vault do workspace; o navegador nunca o vê. 2. Defina o modo de identidade do widget nas configurações do widget (e, opcionalmente, **Require identity** para bloquear mensagens até o login). 3. Emita tokens no lado do servidor com estas claims: | Claim | Valor | | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `sub` | O ID externo estável do seu usuário (obrigatório) | | `workspace_id` | O ID do seu workspace no Switchbord (obrigatório) | | `channel_id` | O ID de canal do widget — exibido nas configurações do widget (obrigatório) | | `aud` | O slug do widget (ou a audiência configurada) | | `iat` / `exp` | Emissão e expiração. TTL máximo de 900 segundos por padrão — emita por carregamento de página, não faça cache de tokens de longa duração | | `iss` | Emissor opcional; precisa corresponder às configurações do widget se configurado | | `email`, `name`, `phone`, `locale`, `avatar_url`, `custom` | Campos opcionais de perfil verificado | ```ts Node.js theme={null} import { createHmac } from "node:crypto"; const b64url = (v: string | Buffer) => Buffer.from(v).toString("base64url"); export function mintWidgetToken(user: { id: string; email?: string; name?: string }) { const now = Math.floor(Date.now() / 1000); const header = b64url(JSON.stringify({ alg: "HS256", typ: "JWT" })); const payload = b64url(JSON.stringify({ sub: user.id, workspace_id: process.env.SWITCHBORD_WORKSPACE_ID, channel_id: process.env.SWITCHBORD_WIDGET_CHANNEL_ID, aud: process.env.SWITCHBORD_WIDGET_SLUG, iat: now, exp: now + 300, email: user.email, name: user.name, })); const signature = createHmac("sha256", process.env.SWITCHBORD_WIDGET_IDENTITY_SECRET!) .update(`${header}.${payload}`) .digest("base64url"); return `${header}.${payload}.${signature}`; } ``` ```php PHP theme={null} function mintWidgetToken(array $user): string { $b64 = fn($v) => rtrim(strtr(base64_encode($v), '+/', '-_'), '='); $now = time(); $header = $b64(json_encode(['alg' => 'HS256', 'typ' => 'JWT'])); $payload = $b64(json_encode([ 'sub' => $user['id'], 'workspace_id' => getenv('SWITCHBORD_WORKSPACE_ID'), 'channel_id' => getenv('SWITCHBORD_WIDGET_CHANNEL_ID'), 'aud' => getenv('SWITCHBORD_WIDGET_SLUG'), 'iat' => $now, 'exp' => $now + 300, 'email' => $user['email'] ?? null, 'name' => $user['name'] ?? null, ])); $sig = $b64(hash_hmac('sha256', "$header.$payload", getenv('SWITCHBORD_WIDGET_IDENTITY_SECRET'), true)); return "$header.$payload.$sig"; } ``` ```python Python theme={null} import hmac, hashlib, json, time, base64, os def _b64url(data: bytes) -> str: return base64.urlsafe_b64encode(data).rstrip(b"=").decode() def mint_widget_token(user: dict) -> str: now = int(time.time()) header = _b64url(json.dumps({"alg": "HS256", "typ": "JWT"}).encode()) payload = _b64url(json.dumps({ "sub": user["id"], "workspace_id": os.environ["SWITCHBORD_WORKSPACE_ID"], "channel_id": os.environ["SWITCHBORD_WIDGET_CHANNEL_ID"], "aud": os.environ["SWITCHBORD_WIDGET_SLUG"], "iat": now, "exp": now + 300, "email": user.get("email"), "name": user.get("name"), }).encode()) sig = _b64url(hmac.new( os.environ["SWITCHBORD_WIDGET_IDENTITY_SECRET"].encode(), f"{header}.{payload}".encode(), hashlib.sha256).digest()) return f"{header}.{payload}.{sig}" ``` Depois, na página para usuários autenticados: ```html theme={null} ``` O segredo de assinatura nunca deve chegar ao navegador. Emita tokens em um endpoint de servidor ou injete-os na página no lado do servidor. Qualquer biblioteca JWT padrão (jsonwebtoken, firebase/php-jwt, PyJWT) também funciona — os exemplos manuais acima existem apenas para evitar uma dependência. ## Verifique a instalação 1. Abra o seu site — a bolha de abertura aparece no canto inferior direito (ou inferior esquerdo, conforme o tema) em um ou dois segundos. 2. `curl https://api.switchbord.ai/api/v1/widgets/YOUR_WIDGET_SLUG/config` retorna `200` com o JSON de configuração do widget. 3. Envie uma mensagem de teste pelo widget — ela aparece na caixa de entrada do Switchbord em tempo real. 4. Responda pela caixa de entrada — o visitante a vê (com o nome do operador) em poucos segundos; se o painel estiver fechado, um selo de não lidas aparece no botão de abertura. 5. Se o modo de IA for **draft** ou **auto-send**, a mensagem de teste produz um rascunho do GBCA (ou uma resposta autônoma) após um breve debounce. ## Resolução de problemas | Sintoma | Causa / correção | | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | O botão de abertura nunca aparece, a URL de config retorna `404` com `origin_not_allowed` ou `widget_not_found` | A origem da sua página não está nas origens permitidas do widget, o slug está errado, ou o widget está desabilitado. Verifique o esquema + host exatos, incluindo `www`. | | Respostas `429` | Limite de taxa do workspace (120 requisições/minuto em todo o tráfego do widget) ou proteção no nível da plataforma. Reduza o ritmo; se o tráfego legítimo exceder isso, fale com o seu operador do Switchbord. | | `identity_required` (`403`) ao enviar | O widget está com **Require identity** ativado — chame `login()` com um token assinado antes de enviar mensagens. | | `identity_secret_missing` (`503`) no login | O workspace ainda não gerou o segredo de assinatura de identidade do widget. | | `identity_signature_invalid` / `identity_*_mismatch` | Token assinado com o segredo errado, ou as claims `workspace_id` / `channel_id` / `aud` não correspondem a este widget. | | O widget carrega mas as mensagens não chegam à caixa de entrada | Verifique no console do navegador se há bloqueio de `connect-src` (CSP) ou um bloqueador de anúncios interferindo na origem da API. | | A conversa reinicia para visitantes anônimos | Comportamento esperado quando o armazenamento do navegador é limpo. Use identidade assinada para conversas duráveis. | ## Prompt de instalação para agentes de programação com IA Entregue isto ao Cursor, Claude Code, Copilot ou qualquer agente de programação que trabalhe no seu site. Substitua os dois placeholders, cole e deixe-o executar. O prompt está intencionalmente em inglês, pois foi feito para ser colado literalmente em agentes de programação que operam em inglês. ```text theme={null} Install the Switchbord chat widget on this website. CONTEXT - Widget script URL: https://api.switchbord.ai/widgets/YOUR_WIDGET_SLUG/embed.js (replace YOUR_WIDGET_SLUG; self-hosted Switchbord replaces the domain too) - The site's public origin(s) must already be allowlisted in Switchbord (Settings -> Integrations -> Channels -> Website widget). Origins in use: YOUR_SITE_ORIGINS - The widget is a single async script tag. It injects a launcher button and an isolated iframe. No npm package, no build step, no API key in the browser. TASK 1. Detect the site's framework/stack by inspecting the repository. 2. Add the script tag so it loads once on every public-facing page, before : - Next.js App Router: use next/script with strategy="lazyOnload" in app/layout.tsx. - Next.js Pages Router: use next/script in pages/_app or _document (body, not head). - Plain HTML / server templates: add to the shared base layout/footer template. - React SPA (Vite/CRA): inject once from a top-level useEffect, guarded by an element-id check so hot reloads and remounts cannot add it twice. - Do NOT add it to admin-only or checkout-critical pages if the repo clearly separates those layouts; otherwise site-wide is correct. 3. If the site has a Content-Security-Policy (check meta tags, next.config, nginx/vercel headers config), extend it: script-src, frame-src, connect-src must each include https://api.switchbord.ai 4. Do not add any other code, wrappers, or configuration. Do not attempt to call widget APIs from the server. The optional JS SDK is window.SwitchbordWidget (open/close/setVisitor/login) with a pre-load command queue window.SwitchbordWidget.q — only wire it if the task explicitly asks. VERIFY 1. Build/serve the site locally. 2. Confirm exactly one script tag for /widgets/YOUR_WIDGET_SLUG/embed.js is present in the rendered HTML of at least two different pages. 3. curl -s -o /dev/null -w "%{http_code}" https://api.switchbord.ai/api/v1/widgets/YOUR_WIDGET_SLUG/config should print 200 (404 means wrong slug or origin not yet allowlisted — report it, don't work around it). 4. Report: files changed, where the tag was placed, CSP changes made (if any), and the local verification results. Note that the launcher only renders on allowlisted origins, so localhost may not show it unless localhost is allowlisted. ``` Testes em localhost: adicione `http://localhost:3000` (ou a sua porta de desenvolvimento) às origens permitidas do widget durante o desenvolvimento, e remova antes de ir ao ar. Uma lista de permissões vazia libera todas as origens — aceitável para um primeiro teste rápido, não para produção.