Erros e diagnóstico — HookCloud Flow

Antes de repetir uma ação

Abra o Log da conexão.
Veja se o job está Processando, Concluído ou Falhou.
Leia a mensagem em português e copie o código de suporte.
Não repita enquanto houver job ativo.
Se a tentativa provisória foi removida, corrija a URL e só então conecte novamente.
Se a mensagem pedir para atualizar o painel, atualize e confira a rota antes de repetir.

Webhook próprio: erros em português e encerramento rápido

Na conexão inicial por webhook próprio, falhas de callback são limitadas a 3 tentativas, com intervalo mínimo de 5 segundos e timeout de 10 segundos por chamada de validação. O painel usa um cronômetro aproximado de 45 segundos.

Código técnico	Explicação para o assinante	Ação recomendada
`callback_url_required_for_custom_webhook`	A URL do webhook não foi informada.	Preencha uma URL HTTPS pública.
`invalid_callback_url` / `callback_must_use_https`	A URL é inválida ou usa HTTP.	Use uma URL HTTPS completa.
`callback_credentials_forbidden`	A URL contém usuário/senha ou exige autenticação inadequada.	Deixe o GET acessível e valide o verify token no código.
`callback_host_forbidden` / `callback_public_hostname_required`	O hostname é local, interno ou reservado.	Publique em domínio público.
`callback_private_network_forbidden` / `callback_dns_resolves_to_private_network`	O DNS aponta para rede privada ou reservada.	Use endpoint acessível pela internet.
`callback_port_forbidden`	A URL usa uma porta não permitida.	Use HTTPS na porta padrão.
`callback_dns_error`	O domínio não resolve publicamente.	Corrija A/CNAME e aguarde a propagação.
`callback_http_401` / `callback_http_403`	A Meta foi bloqueada por autenticação, firewall ou Access.	Libere o GET de verificação.
`callback_http_404`	A rota não existe ou o caminho está errado.	Confira e publique a URL completa.
`callback_http_5xx`	O servidor ou função retornou erro interno.	Revise logs e disponibilidade.
`callback_tls_error`	O certificado HTTPS é inválido ou incompleto.	Corrija o TLS.
`callback_challenge_mismatch`	O endpoint não devolveu exatamente `hub.challenge`.	Retorne o challenge puro quando o token for válido.
`callback_timeout`	O GET demorou demais.	Responda rapidamente, sem trabalho pesado.
`callback_readback_mismatch`	A Meta não confirmou a rota na leitura posterior.	Atualize o painel antes de tentar novamente.
`callback_meta_timeout` / `callback_meta_unavailable` / `callback_transport_error`	Houve indisponibilidade ou timeout entre HookCloud e Meta.	Atualize e confira o estado antes de repetir.

Falha segura: tentativa removida

Quando não há rota remota confirmada e o erro é determinístico, a HookCloud limpa a conexão provisória e os registros criados somente para aquela tentativa. O assinante corrige o endpoint e inicia um novo onboarding.

Estado remoto incerto: recuperação conforme elegibilidade

Em timeout depois de uma possível escrita ou leitura divergente, a tentativa é encerrada e a HookCloud verifica a segurança do descarte local. Quando elegível, o próprio assinante pode descartar e tentar novamente. Configurações remotas não são apagadas pelo descarte.

Falha de callback: corrigir e tentar novamente

O painel distingue Falha na configuração do webhook, falha interna da HookCloud, falha temporária de comunicação com a Meta e rota ainda inconclusiva. Leia a causa e a orientação exibidas. Uma falha de callback não comprova banimento e não deve ser confundida com uma operação ainda em andamento.

Quando a falha for de configuração, confira a URL pública HTTPS, o token de verificação, o retorno do challenge, DNS/TLS e bloqueios de acesso no sistema que recebe o webhook. A documentação de webhook detalha cada requisito. A HookCloud trata defeitos próprios e orienta o diagnóstico quando a causa não estiver confirmada.

Falhas seguras de uma conexão provisória podem ser limpas automaticamente. Se uma tentativa encerrada permanecer no painel e houver a opção de descarte, use-a, confirme o resultado e inicie novamente Conectar com a Meta após corrigir a causa. O descarte mantém o histórico e libera a tentativa elegível; não apaga configurações remotas na Meta.

A disponibilidade do descarte é conferida pelo servidor. Uma conexão anterior saudável, transferência pendente, rota compartilhada ou conflito de propriedade não será removido só porque existe uma mensagem de erro. Se a opção não estiver disponível ou a revisão persistir, informe o código da operação ao suporte. Não é necessário chamar o suporte para descartar uma tentativa que o próprio painel já liberou para essa ação.

Catálogo de erros do Flow

Código/mensagem	Significado	Ação
workspace_invite_accept_failed	Falha no aceite do convite.	Use o link mais recente; se persistir, reenvie o convite e informe Invite ID.
community_profile_create_failed	Perfil comunitário conflitante/indisponível.	Saia e entre novamente; suporte pode reconciliar identidade.
meta_authorization_missing_scopes	Token não recebeu escopo esperado.	Messaging ausente bloqueia; management ausente limita. Reautorize com conta correta.
missing_waba_target	Token não acessa a WABA selecionada.	Confirme BM/WABA e permissões; refaça onboarding.
asset_handoff_confirmation_required	Ativo já vinculado a outro workspace.	Confirme a transferência no painel.
partial_waba_transfer_unsafe	WABA tem outros números e não pode ser movida parcialmente.	Transfira/revise a WABA completa com suporte.
asset_transfer_in_progress_webhook_update_blocked	A conexão está em transferência.	Aguarde o estado Processando; não repita.
M4_16_4_CASE_RECONNECT_REQUIRED	Onboarding anterior não concluiu ou WABA inacessível.	Refaça Embedded Signup.
meta_webhook_routing_readback_mismatch	Callback lido na Meta difere do esperado.	Não force; valide URL e use alteração/reaplicação.
callback_dns_unresolvable	Domínio não resolve.	Corrija DNS e certificado.
HTTP 403 callback verification	Endpoint recusou challenge.	Liberar GET e devolver hub.challenge.
response does not match challenge	Resposta GET contém JSON/HTML.	Devolver somente o challenge.
Unsupported get request / object inaccessible	ID inválido, ativo removido ou token sem acesso.	Confirme ID e permissões; frequentemente exige reconexão.
rate limit / 429	Chamadas excessivas.	Pare loops, aplique backoff e cache.
admin_not_authorized	Conta não possui papel administrativo para a ação.	Entre com usuário correto/MFA quando aplicável.
Aguardando plataforma externa	A conexão Meta concluiu, mas o Chatwoot ainda não assumiu a rota.	Crie a inbox e clique “Verificar Chatwoot”.
external_conflict / conflito externo	A rota detectada pode afetar outros números da mesma WABA.	Não force callback global; envie Connection ID ao suporte.
Chatwoot recebe saída, mas não entrada	Token funciona, porém o callback externo não foi confirmado.	Verifique a rota no Flow e remova configurações concorrentes.

Chatwoot conectado, mas mensagem não chega

Confirme no card: rota externa confirmada, fallback desativado e Phone Number ID igual ao salvo na inbox. Em WABAs com vários números, o WABA ID sozinho não identifica qual número foi configurado.

Erros comuns de conexão dentro da janela da Meta

A seleção mostra “Não qualificado”?

O rótulo da Meta não revela a causa exata. Não o trate como confirmação de banimento, qualidade RED, falha de callback ou revisão administrativa da HookCloud. Nem o prefixo +1 555 comprova que o número seja apenas de teste. Veja a imagem ilustrativa, as situações documentadas e o roteiro para conferir mensagem, modalidade, WABA e permissões. Preserve conexões saudáveis e não exclua ativos apenas para tentar novamente.

Além do catálogo técnico do Flow, existe uma página específica e revisada com situações documentadas do Embedded Signup da Meta, em formato visual e com ações seguras para coexistência, migração e Cloud API.

⊗

8 cenários e diagnóstico por código

Permissão administrativa, excesso de códigos, número em outra empresa, restrição, cadastro anterior e escolha incorreta do modo de conexão.

◫

Comparação por imagem

As telas foram inseridas como imagens para o assinante comparar com a janela da Meta.

↗

Ação imediata

Cada cenário traz a correção sugerida antes de repetir o onboarding.

Abrir a aba de erros comuns na janela da Meta →

O limite de mensagens não aumentou

Confira primeiro a etapa: de 250 para 2.000, a Meta analisa um caminho de verificação ou de uso e pode aprovar ou negar. A verificação, sozinha, não garante aumento. Nas etapas posteriores, a regra combina uso de metade do limite atual nos últimos 7 dias com alta qualidade em todos os números e templates. Volume ou um aumento anterior não comprovam todos os critérios; não force disparos.

Se a Meta já mostra uma faixa maior e a HookCloud mostra a anterior para o mesmo portfólio, confira última sincronização, IDs e possíveis erros de consulta. A divergência pode indicar um dado desatualizado; não prova redução pela Meta. Leia o guia de todas as faixas: 250, 2.000, 10.000, 100.000 e ilimitado, incluindo o prazo de escala e os avisos da interface. Se os critérios estiverem mantidos e o prazo informado tiver passado, solicite verificação à Meta, sem promessa de liberação.

Erros comuns da Meta

Código	Leitura simples	Próximo passo
100	Objeto/parâmetro inválido ou inacessível.	Revisar ID, versão e token.
190	Token inválido/expirado/revogado.	Reautorizar; não apenas repetir.
131026	Mensagem não entregue.	Revisar número, janela, política e payload.
131042	Problema de pagamento/elegibilidade.	Configurar forma de pagamento e revisar WABA.
131047	Janela encerrada.	Usar template aprovado.
131049	Não entregue para manter ecossistema saudável.	Reduzir frequência, melhorar engajamento e não insistir imediatamente.
132000/132001	Template/parâmetro não corresponde.	Revisar nome, idioma e componentes.

Meta e HookCloud mostram estados diferentes

Status atual e contador de risco: quando a HookCloud valida a restauração pela Meta para o mesmo ativo, o BAN anterior abrangido fica resolvido, deixa o contador e permanece na auditoria. Isso não remove RED. Um print ou o status local isolado não bastam para aplicar a resolução; confira a evidência e os horários. Veja a regra de restauração e contagem.

Um telefone pode aparecer como “Registrado” na seleção da Meta e ainda não ter concluído a conexão na HookCloud. Também é possível comparar um dado antigo com uma leitura recente, ou confundir dois ativos da mesma WABA. O nome e o final do telefone não bastam para fechar o diagnóstico.

Compare o mesmo ativo: confira o Phone Number ID e a WABA no WhatsApp Manager e no card da HookCloud. Confira também o workspace e a conexão selecionados.
Compare os horários: veja a última atualização, a última validação e o log da tentativa. Um registro histórico não substitui o estado atual.
Separe as verificações: registro na Meta, validade da autorização, rota de callback e conclusão da operação são estados diferentes.
Atualize pela ação disponível: atualize o painel e confira o log. Recarregar a página não garante uma consulta nova à Meta, e validar a rota não confirma o status operacional ou renova o token.
Se a Meta liberou o número após um bloqueio: confirme o mesmo ativo e siga o guia de atualização pelo próprio assinante quando o Flow continuar desatualizado. Uma verificação atual bem-sucedida de acesso e saúde indica investigar a projeção local; não repita onboarding sem necessidade. Não conclua que o token foi revogado apenas por ter ocorrido banimento; uma validação antiga como válida também não confirma o acesso atual.
Se a divergência persistir após os passos aplicáveis: informe os IDs, horários, resultado da operação e código de suporte para a equipe investigar. Não exclua o ativo na Meta nem desconecte previamente um número saudável só para fazê-lo reaparecer.

Não confunda orientação com correção executada

Esta documentação explica como conferir a divergência. Ela não significa que uma rotina automática foi executada, que o estado já foi corrigido ou que a conexão foi removida. Só considere resolvido depois do resultado confirmado no painel e na operação.

Falha comprovada de HTTPS, challenge ou acesso à URL deve ser corrigida no sistema que recebe o webhook. Timeout, credencial ou leitura divergente precisam de diagnóstico próprio; não conclua automaticamente que o assinante configurou errado. Consulte a configuração do webhook e os estados do seletor Meta.

Credencial revogada, número conectado e status global

O card pode continuar mostrando uma conexão local enquanto a autorização Meta já foi revogada. Um estado CONNECTED não prova que o token ainda aceita chamadas administrativas. Se a validação atual indicar token revogado, credencial inativa ou nova autorização necessária, refaça a conexão oficial; repetir refresh ou consultar logs antigos não recupera a credencial.

Separe três situações:

incidente global: consulte somente Meta Status — WhatsApp Business API;
problema de um número: confira Connection ID, Phone Number ID, autorização, qualidade e callback daquele número;
falha de mensagem/template: localize o POST de status no callback do sistema que fez o envio, correlacionando o wamid.

O Flow não possui histórico de disparos

O HookCloud Flow conecta e gerencia o número; não é disparador, CRM ou caixa de entrada. Em mensagem não entregue, procure entry[].changes[].value.statuses[] no webhook de retorno e compartilhe com o suporte apenas o trecho sanitizado com status, errors, horário e IDs necessários.

O que enviar ao suporte

e-mail do owner;
Workspace ID;
Connection ID, WABA ID e Phone Number ID;
código de suporte;
data/hora e ação realizada;
resultado esperado e recebido;
print sem token.

O que não enviar

token completo;
App Secret;
PIN/senha;
cartão completo;
base de contatos;
documentos desnecessários;
payloads com dados sensíveis sem sanitização.

Ainda precisa de ajuda?

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