← Voltar às documentações

Como criar uma integração Web Chat

Passo a passo para ativar o widget de chat no site com CORS, chave e snippet.

Como criar uma integração Web Chat

O Web Chat é o canal em que visitantes conversam pelo navegador, em um widget no seu site. Um único arquivo JavaScript (/widget.js) exibe o botão, abre o painel e trata envio e recebimento de mensagens — o visitante não instala nada.

Antes de começar

  • Conta no OSBChat com organização selecionada e permissão para criar integrações (admin).
  • Um workflow (bot) já criado ou a intenção de associar um depois (ex.: Suporte, Captação de lead).
  • O domínio exato do site onde o widget vai rodar (para CORS), por exemplo https://www.sua-loja.com. Em desenvolvimento, inclua também http://localhost:PORTA ou o host que você usa (ex.: http://osbchat.internal:3000 em testes internos).

Criar a integração

  1. Vá em Integrações → Nova integração → Web Chat.
  2. Abra a integração recém-criada para configurar.
  3. Defina um apelido (opcional) para reconhecer o canal na lista.
  4. Em Origens permitidas (CORS), informe uma ou mais origens separadas por vírgula ou linha. Só páginas cujo Origin do navegador estiver nessa lista conseguirão chamar a API do widget.
  5. Clique em Gerar chave do widget (ou cole uma chave sua) e Salvar configuração. Com a chave preenchida, o script envia o header X-Widget-Key automaticamente; sem chave, só a validação por CORS protege o uso (não recomendado em produção).
  6. Opcional: Posição do botão (br, bl, tr, tl) e Cor principal em hexadecimal (ex.: #0d9488). Esses valores entram no snippet como data-position e data-primary-color.
  7. Associe o workflow desejado à integração (fluxo padrão de vínculo org + integração + bot), se ainda não estiver associado.
  8. Ative a integração com o interruptor Ativo.

Código no site

No cartão Código no seu site, copie o <script …></script> gerado. Ele já inclui:

  • data-integration-id — ID numérico desta integração;
  • data-api-base — URL pública do OSBChat (ajuste se usar outro host);
  • data-widget-key — quando você salvou a chave;
  • data-position / data-primary-color — quando configurados.

Cole o script uma vez ao final do HTML da página (por exemplo, antes do fechamento do body).

Guia com exemplos por stack: Como embutir o widget Web Chat no site.

Resumo do fluxo técnico

  • O widget chama POST /api/chat/send e GET /api/chat/poll no mesmo host configurado em data-api-base (ou na origem do script).
  • O motor trata a conversa como canal web, igual às outras no painel (bot e atendente humano).

Ver também