Widget de chat

O widget coloca o seu agente em qualquer página web com uma linha de HTML — sem backend, sem programação. O visitante conversa numa janela de chat que abre no canto da página, e a conversa continua entre páginas e recarregamentos.

<script src="https://app.lab019.ai/widget/v1/embed.js"
        data-widget-key="wgt_SUA_CHAVE" async></script>

Cole o snippet no HTML do seu site (de preferência antes do </body>) e pronto: a bolinha de chat aparece no canto da página.

Quando não usar

Se você quer a conversa dentro da sua interface, com o seu backend no meio, use a API pública — o widget é a interface pronta, hospedada por nós. Para WhatsApp, Telegram ou telefone, use os demais canais.

Tudo começa com uma chave de widget (wgt_…), criada no painel em Canais → Widget → Nova chave. A chave amarra o snippet a um agente e guarda a configuração de aparência e comportamento.

Dois pontos importantes:

O agente precisa ser público. O widget atende visitantes anônimos, sem login — só agentes públicos aparecem na criação da chave, e as regras de segurança de agente público (ferramentas anônimas, limites por visitante) valem aqui.
A chave não é um segredo. Ela vai em claro no HTML de qualquer página que a use — é assim mesmo. O que impede outra pessoa de usá-la em outro site são as origens permitidas, abaixo.

Origens permitidas

Cada chave carrega a lista de origens onde o widget pode rodar. Uma origem é o endereço completo do site, com https:// e sem caminho:

https://www.exemplo.com.br
https://loja.exemplo.com.br

Numa página fora da lista o widget até aparece, mas com a aparência genérica (sem a sua cor, título e saudação) e a conversa não conecta: o visitante vê um aviso de falha ao tentar enviar a primeira mensagem. Se o widget carregou "sem a sua cara", o primeiro suspeito são as origens da chave.

Para testes rápidos existe o curinga * (qualquer origem); troque por origens explícitas antes de ir ao ar. O * deve ser o único item da lista — misturá-lo com origens explícitas é recusado, porque a lista pareceria restrita mas estaria aberta (o curinga vence).

Origens são obrigatórias na criação

Como a chave viaja em claro no HTML, ela não pode nascer aberta para qualquer site: ao criar chaves pela API, allowed_origins é obrigatório e não pode ser vazio — para permitir qualquer origem de propósito, envie explicitamente ["*"]. Chaves antigas criadas sem lista continuam funcionando (aceitando qualquer site) até você editar as origens.

O que a chave configura

Na chave (pelo painel) você define o comportamento padrão do widget em todas as páginas: agente, título da janela, cor, saudação, avatar, posição na tela, abertura automática, canais (texto e voz), envio de anexos, transferência para atendimento humano, orçamento diário de créditos e janela de sessão.

Personalizando na página

Qualquer configuração de aparência pode ser sobrescrita por página, com atributos data-* no próprio snippet. O atributo vence a configuração da chave; a chave vence o padrão da plataforma.

<script src="https://app.lab019.ai/widget/v1/embed.js"
        data-widget-key="wgt_SUA_CHAVE"
        data-title="Ajuda da Loja"
        data-color="#e8590c"
        data-greeting="Oi! Como posso ajudar?"
        async></script>

Atributo	Efeito	Valores
`data-widget-key`	A chave do widget — obrigatório	`wgt_…`
`data-title`	Título do cabeçalho da janela	texto
`data-color`	Cor de destaque	`#rrggbb`
`data-greeting`	Primeira mensagem exibida	texto
`data-avatar`	Imagem do agente no cabeçalho	URL `https://…`
`data-position`	Canto da tela	`bottom-right` (padrão), `bottom-left`, `top-right`, `top-left`
`data-auto-open`	Abre a janela ao carregar a página	`"true"`
`data-hide-launcher`	Esconde a bolinha — abrir só por JavaScript	`"true"`
`data-media-input`	Envio de anexos pelo visitante — tipos aceitos, limites e o que o agente faz com os arquivos em Anexos de conversa	`"false"` desliga (ligado por padrão)
`data-channels`	Canais disponíveis na janela	`text` (padrão) ou `text,voice`
`data-consent-text`	Texto de consentimento LGPD exibido quando o agente apresenta um formulário	texto

Controlando por JavaScript

O widget expõe um controle global window.Lab019Widget para a página abrir a conversa a partir da sua própria interface — um botão "Fale conosco", por exemplo:

<a href="#" onclick="Lab019Widget.open(); return false;">Fale conosco</a>

Método	O que faz
`Lab019Widget.open()`	Abre a janela de chat
`Lab019Widget.close()`	Fecha a janela
`Lab019Widget.toggle()`	Alterna aberto/fechado
`Lab019Widget.destroy()`	Remove o widget da página
`Lab019Widget.version`	Versão do widget carregado

Combinado com data-hide-launcher="true", isso permite esconder a bolinha e deixar o chat acessível só pelos seus botões.

Conversa e sessão

A conversa do visitante sobrevive à navegação: ao trocar de página ou recarregar, ele continua na mesma conversa e o agente mantém todo o contexto (desde que no mesmo navegador). A janela reabre limpa — as mensagens anteriores não são reexibidas —, mas nada do que foi dito se perde para o agente. Depois de um período de inatividade — configurável por chave — a próxima visita começa uma conversa nova.

Se a transferência para humano estiver habilitada na chave, o visitante pode ser atendido por uma pessoa na mesma janela, exatamente como descrito em Atendimento humano.

Com data-channels="text,voice" (ou marcando voz na chave), a janela ganha o botão de chamada de voz — o visitante conversa falando, como descrito em Voz. Requer que o agente da chave tenha voz habilitada.

Controles de custo e abuso

Origens permitidas — o widget só roda nos sites que você listou.
Orçamento diário de créditos por chave — limita quanto os visitantes podem consumir por dia; estourou, o widget para de responder até o dia seguinte.
Limites por visitante do agente público continuam valendo.

Gerenciando chaves por API

Para quem automatiza (por exemplo, criando uma chave por cliente num modelo de revenda), as mesmas operações do painel existem como API, autenticada com o token da sua conta — nunca com a própria chave wgt_…:

https://api.lab019.ai/gateway/v1/widget/keys

Método	Rota	O que faz
`POST`	`/keys`	Cria uma chave (`agent_id` e `allowed_origins` obrigatórios — `["*"]` libera qualquer origem de propósito; aceita `title`, `color`, `greeting`, `avatar`, `agent_display_name`, `position`, `auto_open`, `channels`, `handoff_enabled`, `media_input`, `daily_budget_credits`, `session_ttl_seconds`)
`GET`	`/keys`	Lista as chaves da sua organização
`GET`	`/keys/{key}`	Detalha uma chave
`PATCH`	`/keys/{key}`	Altera a configuração (só os campos enviados mudam)
`DELETE`	`/keys/{key}`	Remove a chave — nos sites que a embutem, a conversa deixa de conectar

curl -X POST https://api.lab019.ai/gateway/v1/widget/keys \
  -H "Authorization: Bearer $MEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "atendimento",
    "title": "Ajuda da Loja",
    "allowed_origins": ["https://www.exemplo.com.br"],
    "handoff_enabled": true
  }'

A resposta traz a chave (key) e a configuração completa. Como a chave não é um segredo, ela aparece em todas as listagens — não há rotação; para trocar, crie uma chave nova, atualize o snippet e remova a antiga.

A chave do widget​

Origens permitidas​

O que a chave configura​

Personalizando na página​

Controlando por JavaScript​

Conversa e sessão​

Voz no widget​

Controles de custo e abuso​

Gerenciando chaves por API​

A chave do widget