Chatwoot e plataformas externas

Como esta integração funciona

No modo Chatwoot / plataforma de atendimento, a HookCloud realiza o Embedded Signup pelo App principal, cria a conexão oficial e disponibiliza os identificadores e a credencial necessários. O Chatwoot usa esses dados para operar a WhatsApp Cloud API.

Você não precisa ser Tech Provider

Para este fluxo, basta ser assinante ativo da HookCloud, ter acesso legítimo ao número e concluir a autorização da Meta. A HookCloud faz a intermediação técnica do App e do onboarding. Isso não concede ao assinante o status de parceiro ou Tech Provider da Meta.

HookCloud: Embedded Signup→Copiar número + IDs + token→Criar inbox no Chatwoot→Verificar rota externa

Antes de começar

Assinatura HookCloud ativa e workspace correto.
Número conectado no modo Chatwoot / plataforma externa.
Conexão Meta ativa e canônica.
Phone Number ID, WABA ID e Meta Access Token disponíveis no card.
Acesso administrativo ao Chatwoot Cloud ou à instalação self-hosted.
Permissão do titular da empresa/número para usar a plataforma de atendimento.

Coexistência

Se o número também é usado no aplicativo WhatsApp Business, confirme se a versão do Chatwoot escolhida suporta o seu cenário. A compatibilidade de coexistência pode variar por versão e instalação.

1. Conecte o número na HookCloud

Abra “Conectar WhatsApp”Selecione o workspace correto.

Escolha o destinoMarque Chatwoot / plataforma de atendimento. O campo de webhook próprio ficará oculto.

Conclua o Embedded SignupEscolha a BM, WABA e número corretos e aceite as permissões solicitadas.

Aguarde o card ficar ativoA conexão Meta e a entrega externa possuem estados separados. É normal aparecer “Aguardando configuração no Chatwoot” antes da criação da inbox.

2. Copie os dados do card

Expanda o card do número e copie somente os campos necessários:

Número de telefoneUse o formato internacional, com código do país e DDD, sem espaços, parênteses ou hífens. Exemplo: +5511999999999.

Phone Number IDID técnico do número. No Chatwoot aparece como ID do número de telefone.

WABA IDID da WhatsApp Business Account. No Chatwoot aparece como ID da conta do WhatsApp Business.

Meta Access TokenNo Chatwoot aparece como Chave da API. Trate como senha: não envie em print, e-mail ou canal público.

Número pronto para copiar

Em Informações técnicas e operacionais, use o botão do campo Número para Chatwoot. O painel normaliza e copia o valor em formato internacional, por exemplo +15553811311, sem espaços, parênteses ou traços.

WABA com vários números

Compare sempre o Phone Number ID do card com o salvo na inbox. Dois números da mesma WABA compartilham o WABA ID, mas cada número tem seu próprio Phone Number ID e pode ter uma rota individual diferente.

3. Crie a caixa de entrada no Chatwoot

No Chatwoot, abra Configurações → Caixas de Entrada → Adicionar caixa de entrada.
Escolha WhatsApp e o fluxo de configuração manual/Cloud API.
Defina um nome claro para a inbox, por exemplo Atendimento Loja Centro.
Cole o número, Phone Number ID, WABA ID e Meta Access Token obtidos na HookCloud.
Clique em Criar canal do WhatsApp.
Adicione os agentes que poderão atender as conversas.

Tela do Chatwoot para criar caixa de entrada do WhatsApp com nome, número, Phone Number ID, WABA ID e token Meta — Exemplo sanitizado da configuração. Os valores são fictícios e o token foi ocultado por segurança.

Campo do Chatwoot	Valor da HookCloud	Regra
Nome da Caixa de Entrada	Nome livre	Use um nome que identifique cliente, unidade ou número.
Número de telefone	Número exibido no card	Formato internacional, sem espaços/hífens.
ID do número de telefone	Phone Number ID	Não confundir com o telefone visível.
ID da conta do WhatsApp Business	WABA ID	Precisa corresponder ao mesmo número.
Chave da API	Meta Access Token	Credencial secreta; cole somente no Chatwoot confiável.

4. Use o Callback URL e o Verify Token pelo Flow — não diretamente na Meta

Depois de criar ou abrir uma inbox manual, o Chatwoot exibe um Callback URL e um Webhook Verify Token. Esses dados identificam a rota da própria caixa.

Não altere o App ou a WABA manualmente no Meta for Developers

No ecossistema HookCloud, a rota deve ser aplicada pelo card do número. Uma alteração global feita diretamente na Meta pode redirecionar outros números da mesma WABA.

Guarde os dois valores. Se a detecção automática não confirmar a inbox ou se você estiver reaproveitando uma caixa antiga, use o botão Configurar caixa existente na HookCloud e informe ali a URL e o verify token.

Quando não é necessário informar manualmente

Se o Chatwoot assumir a rota e o Flow confirmar o callback correto por readback, basta concluir os testes reais. O preenchimento manual é uma recuperação segura para caixas existentes ou rotas que não foram assumidas automaticamente.

5. Reaproveite uma caixa existente sem perder o histórico

Uma inbox antiga pode ser reutilizada. Não é necessário apagar conversas, contatos, responsáveis ou o histórico apenas porque o token, Phone Number ID ou a rota foram renovados.

Atualize a mesma inboxInforme o novo Meta Access Token e confirme o WABA ID e o Phone Number ID atuais.

Copie os dados da caixaLocalize o Callback URL e o Webhook Verify Token exibidos pelo Chatwoot.

Clique “Configurar caixa existente”Cole a URL e o verify token no Flow. Não cole esses dados diretamente na configuração global do App.

Aguarde o readbackA HookCloud aplica a rota no Phone Number ID e só confirma quando a Meta retorna exatamente o callback da inbox.

Teste entrada e saídaEnvie uma mensagem ao número e responda dentro da conversa antiga.

Token aceito não significa webhook ativo

O Chatwoot pode salvar um token válido e ainda não receber mensagens se a rota efetiva continuar apontando para um webhook próprio antigo. A caixa só está pronta depois do readback e do teste de mensagem recebida.

Proteção contra falso positivo

Uma URL que já existia antes da reconexão não é mais classificada automaticamente como “Chatwoot verificado”. O Flow compara a rota anterior com a rota atual e exige confirmação explícita da inbox.

6. Verifique a integração na HookCloud

Volte ao card do númeroO estado inicial pode ser “Aguardando plataforma externa”.

Clique “Verificar Chatwoot”O Flow faz uma leitura passiva da rota e não altera o callback.

Se ainda não houver rotaO estado termina como “Chatwoot ainda não assumiu a rota”. Use Configurar caixa existente ou aguarde a plataforma assumir.

Espere “Rota externa confirmada”Sucesso exige o callback efetivo correto no Phone Number ID.

Faça testes reaisTeste mensagem recebida, resposta, mídia, status e template quando aplicável.

Verificação passiva não bloqueia o card

A verificação manual faz uma leitura. A automática faz no máximo três leituras. Enquanto ela estiver em andamento, Configurar caixa existente, Usar webhook próprio e Desconectar continuam disponíveis.

Cronômetro e tempo de processamento

Ação	Comportamento	Orientação
Conectar número	Etapa com escrita e readback; pode levar alguns minutos.	Não feche ou repita durante processamento.
Verificar Chatwoot	Uma leitura manual ou até três leituras automáticas.	É passiva e não bloqueia Configurar caixa existente.
Configurar caixa existente	Aplica callback + verify token e confirma a rota.	Aguarde o resultado terminal antes de repetir.
Transferência protegida	Pode aguardar ownership e rota canônica.	Aguarde a confirmação da conexão atual.
Desconectar	Possui checkpoints e pode oferecer Parar desconexão.	Não inicie nova operação enquanto a fase irreversível estiver em andamento.

Estimativa, não prazo rígido

Se o contador zerar em uma aplicação, aguarde o resultado final. Uma verificação passiva sem rota deve terminar como estado informativo, e não permanecer bloqueando o card.

Chatwoot e prontidão para BSUID

Uma inbox com health verde confirma credenciais e conectividade, mas não prova sozinha que a versão instalada trata contatos sem telefone.

Use uma versão atualizada do Chatwoot.
Teste webhook com contacts[].user_id e messages[].from_user_id.
Permita que wa_id e from venham vazios ou ausentes.
Confirme que status de mensagens preservam statuses[].recipient_user_id.
Para resposta por BSUID, o sistema deve usar o valor de user_id no campo outbound recipient; para telefone, continua usando to.
Não use username como chave primária.

Abrir o guia completo de Usernames e BSUID →

Outros sistemas de multiatendimento

Você pode tentar usar o mesmo modelo em outra plataforma que aceite configuração manual da WhatsApp Cloud API com:

número em formato internacional;
Phone Number ID;
WABA ID;
Meta Access Token;
mecanismo compatível para assumir ou validar a entrega do webhook.

A compatibilidade não é garantida. Peça ao desenvolvedor do sistema para implementar uma lógica equivalente à integração manual do Chatwoot e respeitar a rota específica do Phone Number ID. O assinante não precisa fornecer ao desenvolvedor App Secret da HookCloud, essa chave é de uso exclusivo do sistema da HookCloud.

Mudar depois para um webhook próprio

É possível sair do Chatwoot e apontar o número para n8n, Make, CRM ou backend próprio sem apagar necessariamente o histórico da inbox.

Pare o uso operacional da inboxInterrompa envios e automações concorrentes. Preserve a caixa se quiser manter o histórico.

Na HookCloud, clique “Usar webhook próprio”Informe a URL HTTPS nova.

Aguarde GET, escrita e readbackA HookCloud só muda o modo depois de confirmar a rota no Phone Number ID.

Teste o POSTConfirme que os eventos chegam ao destino novo e que a inbox antiga não continua respondendo.

Um número deve ter um destino operacional por vez

Manter token ativo em vários sistemas pode permitir envios concorrentes mesmo quando apenas um webhook recebe as mensagens. Defina claramente qual sistema atende e automatiza o número.

Segurança do token e responsabilidades

Use o token somente em uma instalação Chatwoot confiável e com acesso administrativo restrito.
Não grave o token em prints, tickets públicos, workflows exportados ou URLs.
Se o token for exposto, interrompa a integração e solicite reautorização/rotação.
A plataforma externa passa a tratar dados de contatos e mensagens sob a responsabilidade do assinante.
Revise política de privacidade, hospedagem, backups, logs, retenção e suboperadores da ferramenta escolhida.

Problemas comuns

Sintoma	Causa provável	Ação
Credenciais inválidas	Token revogado/expirado ou IDs de ativos diferentes.	Reautorize, copie do mesmo card e confirme WABA/Phone ID.
HookCloud continua “aguardando”	A inbox ainda não assumiu a rota.	Use Verificar Chatwoot; se não detectar, use Configurar caixa existente.
Verificação antiga aparece em andamento	Job passivo de uma leitura anterior.	Na versão atual ele termina sem bloquear os demais botões; atualize o painel.
Chatwoot aceita o token, mas não recebe mensagens	A credencial está válida, porém a rota efetiva aponta para fallback ou webhook antigo.	Atualize IDs/token na inbox e use Configurar caixa existente com Callback URL + Verify Token.
Webhook próprio antigo aparece como Chatwoot	Rota anterior ainda aplicada em uma camada da WABA/telefone.	Não considere sucesso. Aplique explicitamente a caixa existente e aguarde o readback exato.
Conflito externo/WABA compartilhada	Uma alteração global poderia afetar outros números.	Use a rota específica do Phone Number ID e envie Connection ID/código de suporte.
Token sem management	Templates, metadados e configuração automática podem ficar limitados.	Reautorize pela empresa correta com as permissões necessárias.
Inbox mostra outro número da mesma WABA	Phone Number ID incorreto.	Compare o ID literal e corrija a mesma inbox.

Referências oficiais

As telas do Chatwoot e da Meta podem mudar. O procedimento específico da HookCloud prevalece para o App e a rota gerenciados pela HookCloud.

Precisa de ajuda?

Envie o e-mail do owner, Workspace ID, Connection ID, Phone Number ID, horário aproximado e o código de suporte para suporte@hookcloud.app. Nunca envie o token completo.