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: nada é apagado às cegas
Em timeout depois de uma possível escrita ou readback divergente, as tentativas são encerradas, mas o estado é preservado para não quebrar uma rota que a Meta pode ter aplicado.
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
Além do catálogo técnico do Flow, existe uma página específica e revisada com os erros mais frequentes do Embedded Signup da Meta, em formato visual e com ações seguras para coexistência, migração e Cloud API.
⊗
7 cenários comuns
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.
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. |
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.