Integração: referência técnica para desenvolvedores

Esta referência se destina a desenvolvedores que integram o reactive.chat a um site, aplicativo ou backend. Ela descreve as interfaces e os fluxos conforme implementados no código, com nomes, tipos, padrões e casos de erro.

Como configurar aparência, textos, tela inicial, regras, tours, testes A/B e a personalidade da IA está descrito em Personalização. Como usar a conta e o painel de atendimento está no Manual.

Visão geral

Your visitors' browser                      reactive.chat                         your server
----------------------                      -------------                         -----------
loader.js  --(trigger)-->   core.<hash>.js  cdn.reactive.chat
   window.ReactiveChat (API, events)
   WebSocket rc.v1  <------------------->   ws.reactive.chat/rc_wss/
   HTTP fallback (SSE/Poll) <----------->   ws.reactive.chat/rc_wss/h/
                                            chat server  --- POST (signed) ---->  customer data endpoint
                                                         --- POST (signed) ---->  webhook receiver
                                            reactive.chat/v1  <--- Bearer -----  REST API / MCP
identify(userHash)  <-------------------------------------- HMAC-SHA256 ------  identity secret

No lado do cliente, você incorpora uma tag script e, opcionalmente, controla o widget por window.ReactiveChat. No lado do servidor, você assina a identidade dos usuários conectados, responde a solicitações de dados de clientes se necessário, recebe webhooks e usa a API REST.

Capítulos

Conceitos básicos

• Arquitetura e fluxo – os componentes, como funcionam juntos, versões e distribuição
• Início rápido – incorporar, cadastrar o domínio, CSP, verificar

No navegador

• Referência da tag script – todos os atributos data-rc-* e fontes de configuração
• API JavaScript – todos os comandos de ReactiveChat(…)
• Eventos – on/off e eventos DOM
• Identificar visitantes e passar contexto – identify, userHash, exp, track
• Aplicações de página única e mudanças de página
• Segurança e Content Security Policy

Conexão e distribuição

• Domínio próprio e proxy first-party – nginx, Apache, Caddy
• Transporte: WebSocket, fallback HTTP e reconexão – protocolo, códigos de erro e de fechamento

No seu servidor

• Endpoint de dados de clientes – consulta e importação de pedidos
• Webhooks – eventos, assinatura, novas tentativas, REST hooks
• API do servidor (REST v1) e MCP
• Integrações e canais – WhatsApp, Messenger, Instagram, Telegram, SMS, e-mail

Outros locais de integração

• Aplicativos móveis – o chat em uma WebView
• Smart Answer – resposta de IA na pesquisa do seu site

Operação

• Integração de privacidade – consentimento, armazenamento, texto de privacidade
• Limites e cotas
• Solução de problemas e checklist

Outras páginas sobre o assunto

• Incorporar o widget – a versão resumida
• Detalhes técnicos – medidas de tamanho, acessibilidade e contraste
• Abrir o chat por um link ou botão próprio
• O card promocional no chat
• Dados de clientes no chat
• Domínio próprio (first-party)
• Fallback HTTP
• Inserir automaticamente o texto de privacidade

Termos

• Chave do site – a chave pública de um projeto (24 caracteres), incluída no código de incorporação. Não é um segredo.
• Projeto – um site ou aplicativo com configurações próprias; vários projetos formam um espaço de trabalho.
• Painel de atendimento – a interface na qual sua equipe responde.
• Usuário confirmado – um visitante cuja identidade foi assinada pelo seu servidor por meio de userHash.
• Carregador / núcleo – a pequena parte de carregamento loader.js e a parte principal core.<hash>.js, carregada depois.

Todas as partes da documentação em um só lugar: Documentação.