Como integrar a API de WhatsApp da StackZap com o Chatwoot

A integração StackZap com Chatwoot conecta a sessão de WhatsApp ao fluxo de atendimento. A StackZap fornece a API e os eventos da instância; o Chatwoot organiza a caixa de entrada, conversas e trabalho da equipe. Os detalhes de cadastro, callbacks e campos devem seguir o manual correspondente à versão dos dois sistemas.

1. 01Crie a instância StackZap
2. 02Cadastre os dados no fluxo Chatwoot
3. 03Valide callback e conexão
4. 04Faça uma mensagem de teste

O que preparar

• A URL do ambiente StackZap e a credencial adequada, obtidas pelo painel Cloud ou pela instalação própria.
• Uma instância pareada e operacional.
• A URL da instalação Chatwoot e as credenciais que o manual da integração solicitar.
• Um endpoint público para callbacks, quando exigido pelo fluxo utilizado.

Guarde tokens e segredos em local protegido. Não inclua esses valores em capturas de tela ou chamados. A URL de cada ambiente Cloud é individual, portanto não use um endereço de outro cliente como referência.

Configure e valide em etapas

Siga o procedimento atual em manuais StackZap e confira as operações disponíveis na referência da API. Valide a conexão, verifique o callback e envie uma mensagem de teste para um contato autorizado antes de envolver a equipe de atendimento.

Se uma mensagem não chegar ao Chatwoot, diagnostique cada fronteira separadamente: estado da instância, resposta de envio, evento/webhook, URL de callback e log da integração. Isso ajuda a localizar se o problema está na conexão, no transporte do evento ou no processamento no Chatwoot.

O formato de integração pode mudar entre versões. Use os manuais atuais como fonte dos nomes de campos e não misture credenciais da API StackZap com a senha de administrador do Chatwoot.

Entenda as responsabilidades de cada sistema

A StackZap mantém a conexão da conta e expõe operações e eventos da API. O Chatwoot organiza a caixa de entrada, usuários, equipes e conversas. A integração conecta esses fluxos, mas não elimina a necessidade de configurar cada componente e validar a comunicação entre eles. É útil desenhar a direção do tráfego: onde começa a mensagem, qual serviço a encaminha, em que endpoint o evento chega e qual sistema armazena o resultado.

O manual da versão define se a configuração acontece por integração pronta, endpoint de callback, extensão ou combinação de componentes. Não misture exemplos de versões diferentes do Chatwoot ou StackZap. Confirme requisitos de URL pública, formato de telefone, caixa de entrada, permissões e eventos. Em ambientes de desenvolvimento local, URLs localhost não são acessíveis a serviços remotos; use ambiente de teste com endpoint público protegido quando necessário.

Fronteiras da integração

Faça um inventário antes de configurar

Registre a URL do ambiente StackZap, o ID da instância, a versão de ambos os produtos, a URL pública do Chatwoot e quais credenciais específicas o manual exige. Identifique quem administra cada serviço e onde os segredos serão guardados. Para StackZap Cloud, copie a URL em contas.stacklab.digital; cada ambiente possui endereço próprio. Para self-hosted, use o domínio da instalação configurada pelo operador.

Decida que número será usado, que equipe responderá e como mensagens recebidas serão encaminhadas. Uma integração funcional precisa também de uma pessoa responsável pelo inbox e por acompanhar falhas. Não use contas pessoais sem autorização da organização nem credenciais administrativas amplas se a documentação permitir escopo menor.

Configure em etapas verificáveis

1. Confirme que a instância está pareada e com estado conectado.
2. Siga o manual correspondente às versões dos dois produtos.
3. Cadastre a URL e credenciais da StackZap no ponto indicado pelo Chatwoot.
4. Configure callback/webhook público se o fluxo exigir.
5. Valide uma mensagem de teste de entrada e uma de saída com contato autorizado.
6. Confira a conversa no inbox, o estado do evento e os logs sanitizados.

Faça uma alteração por vez e anote a resposta de cada etapa. Se a conexão falhar, reverta a última configuração e teste o componente isoladamente. Isso evita corrigir ao mesmo tempo endpoint, token, inbox e firewall sem saber qual mudança resolveu.

Diagnostique por fronteira

Se uma mensagem enviada pelo Chatwoot não chegar, confira se a instância está conectada, se a chamada atingiu a URL correta, se a autenticação foi aceita e se a resposta de envio trouxe um resultado. Depois examine a integração do Chatwoot e os eventos associados. Se a StackZap registra envio, mas a conversa não aparece no inbox, investigue o callback e o processamento Chatwoot.

Se mensagens recebidas não aparecem, confirme que o evento de entrada está habilitado, a URL de callback é acessível de fora e TLS está válido. Valide assinatura conforme documentação, observe status HTTP e verifique filas internas. Se o endpoint responde com sucesso antes de persistir os dados, um erro posterior pode perder o evento; use armazenamento durável e processamento desacoplado.

Também confira mapeamento de identidade. Diferentes formatos de telefone, país ou identificador de contato podem resultar em conversas separadas. Use a documentação para definir normalização e não altere IDs manualmente em banco sem compreender as relações. Eventos duplicados podem criar interações repetidas; use ID de entrega para deduplicação onde disponível.

Proteja credenciais e callbacks

Guarde API Key e tokens do Chatwoot como secrets distintos. Não coloque chaves no frontend, query string, repositório ou screenshot. A assinatura do webhook deve ser verificada antes de consumir o evento. Restrinja acesso ao callback e mascare headers em logs. O endpoint precisa validar corpo, tipo de conteúdo, tamanho e evento permitido.

Uma integração pode carregar conteúdo de conversas e números de telefone. Minimize o que é armazenado, proteja backups e logs e defina quem pode consultar dados. Em ambientes de teste, use dados fictícios. Compartilhe com suporte apenas IDs de correlação, faixa de horário e mensagens de erro sanitizadas.

Evite mensagens duplicadas

Integrações podem repetir requisições quando uma resposta demora ou o webhook não é confirmado. Mantenha uma correlação entre a conversa e o evento de negócio e evite repetir uma ação quando o resultado ainda é desconhecido. Use fila ou log de processamento para acompanhar pendências. Se o operador clicar duas vezes, o backend deve detectar a mesma solicitação ou pedir confirmação antes de gerar outro envio.

Defina também o tratamento de desconexão: pausar temporariamente a saída, enfileirar com validade ou alertar a equipe. Mensagens antigas podem perder contexto. Após reconectar, retome gradualmente e consulte a situação dos jobs em vez de reenviar tudo de uma vez.

Teste de ponta a ponta

Faça primeiro um teste de saída para um número da equipe e confira o retorno no Chatwoot. Depois teste uma resposta recebida e verifique evento, callback e conversa. Teste ainda uma indisponibilidade temporária do receptor para confirmar retry e deduplicação. Não valide apenas que o botão salvou as configurações; acompanhe o caminho da mensagem de ponta a ponta.

Lista de verificação

• Versões e manuais compatíveis identificados.
• URLs e IDs pertencem ao ambiente certo.
• Instância conectada e destinatário de teste autorizado.
• Segredos guardados em cofre e fora do frontend.
• Callback público com TLS e verificação de assinatura.
• Eventos persistidos antes de confirmar recebimento.
• Duplicatas e timeouts tratados sem reenviar cegamente.
• Testes de entrada e saída concluídos no inbox esperado.
• Logs redigidos e responsáveis definidos para suporte.

Organize a operação da equipe

Depois do teste, defina quem atende o inbox, quem administra a conexão e quem investiga falhas da API. Um operador de atendimento não precisa necessariamente receber acesso à API Key ou ao painel de infraestrutura. Separe perfis e conceda apenas os recursos necessários. Documente como transferir a conversa para outra equipe sem criar uma segunda integração ou copiar dados para planilhas pessoais.

Escreva um procedimento de contingência para quando a instância cair: identificar o estado, pausar campanhas ou notificações, informar a equipe, iniciar reconexão pelo processo autorizado e validar antes de reabrir envios. Se o Chatwoot continuar recebendo mensagens, indique quais podem permanecer em fila. Não incentive agentes a parear de novo sem coordenação.

Diferencie falha no inbox e falha no WhatsApp

Uma mensagem pode aparecer no Chatwoot sem ter sido enviada ao WhatsApp, ou pode ser enviada e não ter o retorno sincronizado. Use IDs e timestamps de cada lado para correlacionar. Compare a resposta StackZap, evento de entrega e registro da conversa. Evite concluir entrega somente porque o balão apareceu na interface administrativa.

Se a resposta chegou à StackZap mas não ao Chatwoot, examine callback, autenticação, assinatura, resposta HTTP e fila de eventos. Se o Chatwoot criou a mensagem mas a StackZap não recebeu a chamada, revise configuração da integração, credencial e rota. Faça cada investigação num ambiente controlado para não reenviar conteúdo ao contato.

Planeje mudanças e atualizações

Atualize StackZap e Chatwoot de forma controlada, anotando versões e compatibilidade indicada pelos manuais. Faça primeiro em staging com inbox e número de teste. Confira campos de callback, schema de evento e permissões após cada upgrade. Uma integração pode continuar autenticando enquanto um campo mudou, por isso valide entrada e saída de ponta a ponta.

Antes de mudar URL do Chatwoot ou proxy, confirme certificados, DNS e acesso de fora. Se callback ficar indisponível, monitore retries e backlog. Depois da migração, deixe a URL antiga disponível pelo período necessário conforme seu plano e remova-a quando não receber eventos. Não mantenha tokens ativos em dois locais indefinidamente.

Métricas de saúde da integração

Acompanhe latência entre mensagem recebida e visível no inbox, erros de callback, assinatura inválida, falhas de autenticação, jobs repetidos e status da instância. Segmente por ambiente e canal. Um alerta deve apontar onde agir e ter um runbook; notificar a equipe por cada webhook cria ruído. Proteja conteúdo e números nas métricas.

Faça revisão periódica dos acessos, credenciais e caixas de entrada. Desative agentes que não trabalham mais no canal, confirme o responsável pela instância e revise a rota de suporte. Se o problema envolver dados pessoais, siga a política interna de incidente e evite copiar conversas para canais de diagnóstico abertos.

Faça manutenção da conexão

Inclua o status da instância no procedimento diário do inbox e defina uma pessoa que receba o alerta de desconexão. Durante a recuperação, pause envios automáticos, conclua o pareamento no celular autorizado e confirme um teste controlado antes de retomar a equipe. Uma conversa visível no Chatwoot não garante que a sessão do WhatsApp esteja conectada; monitore as duas partes.

Revise periodicamente se o callback ainda aponta para a URL pública correta, se o certificado TLS é válido e se os segredos continuam restritos. Mudanças de domínio, proxy ou versão precisam de teste de ponta a ponta. Documente essas dependências para que uma atualização de infraestrutura não interrompa o fluxo de atendimento.

Mantenha um ambiente de homologação

Use um inbox e um número de teste separados para validar configurações, upgrades e regras de callback. Evite apontar testes para a caixa de entrada de produção, pois uma mensagem pode ser atendida como se fosse de cliente. O ambiente de homologação precisa de URL, credenciais e secrets próprios; não copie o token de produção para acelerar a configuração.

Antes de liberar uma alteração, simule mensagem recebida, resposta enviada, instância desconectada e callback indisponível. Compare os IDs que aparecem em cada produto e confirme que a aplicação não associa conversa de um cliente a outro. Depois do teste, limpe dados sintéticos segundo sua política.

Registre o resultado do teste, as versões e quem aprovou a liberação. Mantenha um checklist para repetir depois de cada upgrade ou mudança de domínio. Um pequeno conjunto fixo de casos de ponta a ponta ajuda a detectar regressões sem depender da memória do operador.

Defina o responsável pelo callback

A URL receptora precisa ter dono técnico para monitorar certificado, DNS, disponibilidade e alterações de firewall. Registre também quem atualiza a integração quando Chatwoot ou StackZap muda de versão. Se o endpoint for hospedado por outro time, combine uma forma de avisar sobre manutenção e uma pessoa para validar eventos após a mudança. Um callback esquecido pode continuar recebendo dados mesmo quando ninguém acompanha a caixa de entrada.

Depois de cada atualização, valide uma conversa real de teste do início ao fim e confirme que resposta, evento e registro no inbox estão consistentes. Se algo divergir, pause novas alterações e use os IDs de correlação para localizar a fronteira afetada.