Integrações e canais (técnico)

Os canais trazem mensagens de outros serviços para o mesmo painel de atendimento do chat do site; as integrações enviam eventos a outros serviços ou buscam conhecimento neles. Esta página descreve a tecnologia. Como operá-los na conta está no Manual.

Status: os canais e a maioria das integrações foram testados com respostas simuladas dos provedores, mas ainda não com todas as contas reais. O webhook assinado está concluído (com a limitação mencionada lá); para todos os outros provedores, verifique o log da integração depois de ativá-la. Trate-os como beta.

Regras comuns

• Endereços de callback têm o formato https://reactive.chat/kanal/<kanal>/<SITE_KEY>. A chave do site está na conta, em Projeto → Instalação.
• Toda rota de entrada verifica a assinatura do provedor. Sem o segredo do provedor, nada é aceito.
• Credenciais são armazenadas de forma criptografada e separadas do restante da configuração.
• Respostas da sua equipe vão ao provedor por uma fila de saída; uma plataforma travada não bloqueia nenhum chat.
• Tamanho da mensagem: mensagens recebidas acima do limite do plano são encurtadas e marcadas com [...] (Limites).
• Anexos dos canais (e-mail, fotos do Telegram) passam pela mesma verificação do widget (tipo, tamanho, cota). Arquivos rejeitados aparecem no texto como “[Anexo não aceito: …]”, no idioma padrão do projeto (de, en, pl; caso contrário, inglês).

WhatsApp, Messenger, Instagram

Configure na conta, em Integrações. Você precisa do seu próprio aplicativo no Meta Developer Dashboard; suas mensagens não passam por uma conta nossa.

• Callback URL: https://reactive.chat/kanal/whatsapp/SITE_KEY, …/kanal/messenger/SITE_KEY ou …/kanal/instagram/SITE_KEY
• Verify Token: uma string aleatória longa que você informa de forma idêntica na Meta e conosco (comparação em tempo constante).
• App Secret: usado para verificar a assinatura de cada callback. Sem App Secret, a rota de entrada não aceita nada.
• Access Token: usado para enviar em seu nome.

Regras das plataformas que fazem entregas falharem silenciosamente:

• WhatsApp: nas 24 horas após a última mensagem do cliente, você pode responder livremente; depois, somente com um modelo aprovado (tipo UTILITY, exatamente um marcador {{1}}). Informe o nome dele na configuração; fora da janela, não enviamos livremente.
• Instagram: o cliente precisa escrever primeiro.
• Messenger: das etiquetas de mensagem, apenas HUMAN_AGENT é aceita; rejeitamos as outras.

A Meta espera a resposta a um callback em até cinco segundos; nossa rota de entrada apenas aceita e coloca na fila.

Telegram, SMS, e-mail

Esses canais pertencem ao projeto e são configurados em Projeto → Canais.

• Telegram: seu próprio bot. Ao salvar o token do bot, cadastramos o endereço de callback https://reactive.chat/kanal/telegram/SITE_KEY por setWebhook, com um secret_token aleatório que todo callback deve conter. Por padrão, o assistente também responde.
• SMS: pela sua conta Twilio (integração Twilio). Para o número, informe https://reactive.chat/kanal/sms/SITE_KEY em “A message comes in”; X-Twilio-Signature é verificado. Por padrão, o assistente também responde.
• E-mail: sua caixa de correio é consultada por IMAP a cada minuto; as respostas vão pelo seu SMTP (caso contrário, pelo nosso serviço de envio com Reply-To). Nenhum e-mail antigo é buscado ao ativar. A associação à conversa é feita por In-Reply-To/References; caso contrário, por remetente e assunto dos últimos 30 dias. Não são importados: avisos de ausência, relatórios de entrega, listas de e-mail, mensagens marcadas como spam, mais de 20 e-mails por remetente e por hora (300 por projeto). Por padrão, o assistente não responde a e-mails; quando ativado, suas respostas incluem Auto-Submitted: auto-replied.

Lacuna conhecida: se uma entrega ao provedor falhar permanentemente (número bloqueado, janela encerrada), o motivo aparece no log da integração, mas ainda não na conversa.

Integrações

Você ativa as integrações na conta, em Integrações. Cada uma tem suas próprias credenciais (chave, token, endereço ou login no provedor). Os eventos (conversation.created, message.created, handoff.requested, csat.submitted, fehlerfall.erstellt) passam por uma fila com novas tentativas:

• até cinco novas tentativas com intervalos crescentes (de 1 s a pouco mais de 10 minutos),
• um mecanismo de interrupção por provedor e espaço de trabalho: após 5 erros em 60 segundos, pausa de 30 segundos,
• eventos com mais de uma hora não são mais entregues,
• um chat nunca espera por uma integração.

Provedores no código:

• Eventos para seus próprios sistemas: webhooks (assinados; veja Webhooks), Zapier, Make, n8n (por REST hooks)
• Chat da equipe: Slack, Microsoft Teams, Discord
• Tickets e CRM: Zendesk, Freshdesk, HubSpot, Pipedrive, Jira, Linear, GitHub
• Lojas: Shopify, WooCommerce, Shopware, Stripe
• Conhecimento: rastreador de sites, WordPress, Notion, Confluence, Google Drive
• Análise e erros: Google Analytics 4, Matomo, Plausible, Sentry
• Agendamentos: Cal.com
• Canais: WhatsApp, Messenger, Instagram, Telegram, Twilio, e-mail

Você não pode cadastrar provedores próprios. Para suas próprias conexões, use webhooks, a API do servidor ou MCP.

Recursos de loja no chat (como “Adicionar ao carrinho” para WooCommerce, Shopify e Shopware) são habilitados pelo reactive.chat por projeto; só funcionam no host da loja cadastrado e não têm uma API JavaScript própria.

Aplicativos móveis

Para aplicativos, não há SDK nativo, mas há uma página de incorporação para WebViews: Aplicativos móveis.

A seguir: Aplicativos móveis