Conectar o WhatsApp — HookCloud Flow

Escolha o destino das mensagens

Sem URL obrigatória

Chatwoot / plataforma de atendimento

Use quando o atendimento será feito em uma plataforma externa. A HookCloud mantém um fallback técnico e depois verifica se a plataforma assumiu a rota.

Abrir o passo a passo do Chatwoot →

URL própria

Webhook próprio

Use para n8n, Make ou backend próprio. Informe uma URL HTTPS pública que responda ao GET de verificação, aceite os POSTs da Meta e não exija login no challenge.

Ver a validação em 3 tentativas →

Um único Embedded Signup

As duas opções usam o mesmo botão “Conectar com a Meta”. O modo escolhido altera apenas como a entrega dos eventos será gerenciada.

Antes de conectar com webhook próprio

O callback precisa estar publicado e acessível pela internet antes de abrir o Embedded Signup. A HookCloud não consegue corrigir automaticamente uma rota inexistente, protegida por login ou que responda ao challenge no formato errado.

Requisito	Como deve funcionar	Falha comum
URL pública	HTTPS completo, domínio público e porta padrão.	HTTP, localhost, IP privado, domínio reservado ou porta não permitida.
DNS e certificado	O domínio resolve publicamente e o certificado TLS é válido.	DNS ainda não propagado, certificado expirado ou cadeia incompleta.
GET de verificação	Valida `hub.verify_token` e devolve exatamente `hub.challenge`.	Retornar JSON, HTML, texto extra ou challenge incorreto.
Acesso ao GET	A rota de verificação fica acessível sem login, Basic Auth ou Cloudflare Access.	Resposta 401/403, firewall ou tela de autenticação.
POST de eventos	Aceita JSON e confirma rapidamente com HTTP 2xx.	Rota 404, erro 5xx ou processamento pesado antes da resposta.

Chatwoot é um fluxo diferente

No modo Chatwoot/plataforma externa, você não informa uma URL própria durante a conexão inicial. A política de três tentativas desta página é específica para o callback próprio informado pelo assinante.

Tipos de conexão

Modo	Quando usar	Cuidados
Coexistência / número já existente	Manter o aplicativo WhatsApp Business e conectar o mesmo número à plataforma, quando elegível.	Siga todas as etapas de importação e mantenha o app atualizado.
Cloud API / número novo ou migrado	Usar o número apenas na plataforma oficial.	O número pode exigir cadastro/PIN e não deve permanecer ativo em outra integração incompatível.

Botão “Conectar com a Meta”

Clique uma vezO painel abre a janela oficial da Meta.

Escolha o Business PortfolioUse a empresa correta; trocar de BM pode gerar nova WABA e identidade técnica.

Escolha/crie a WABAConfirme o nome e os ativos.

Selecione o númeroRevise o final do telefone antes de avançar.

Aceite as permissõesMensagens são obrigatórias. Gerenciamento ausente resulta em modo limitado.

ConcluaAguarde o painel processar; não recarregue durante o popup.

Permissões e modo limitado

Escopo	Efeito
whatsapp_business_messaging	Obrigatório para a conexão. Sem ele, o Flow não conclui.
whatsapp_business_management	Pode ser opcional para conectar. Sem ele, templates, metadados e certas alterações administrativas ficam limitados.
business_management / public_profile	Podem aparecer no token, mas não substituem os escopos do WhatsApp.

Acompanhamento e estados

O acompanhamento exibe autorização, criação provisória da conexão, validação de WABA/número, callback e conclusão. Um estado Processando é normal enquanto houver um job ativo. Não repita o onboarding durante essa etapa.

3×

Até 3 tentativas

Falhas relacionadas ao callback próprio são encerradas na terceira tentativa.

Intervalo mínimo

Há pelo menos 5 segundos entre as tentativas. A execução real pode ganhar alguns segundos conforme o worker.

10s

Timeout por validação

Cada chamada de validação do callback pode aguardar até 10 segundos antes de ser classificada.

Cronômetro de aproximadamente 00:45

No modo webhook próprio, o painel mostra uma estimativa de 45 segundos e informa que serão feitas no máximo três tentativas. Não feche, recarregue, repita ou cancele a conexão enquanto o resultado estiver em processamento.

O que acontece quando o webhook está errado

1. O erro é identificadoO painel traduz o problema para português e mostra o possível motivo: HTTPS, DNS, autenticação, rota 404, TLS, timeout, challenge incorreto ou indisponibilidade.

2. A HookCloud tenta no máximo três vezesAs tentativas de callback usam intervalo mínimo de cinco segundos e não continuam indefinidamente.

3. Falha segura é limpaQuando a Meta não aplicou nenhuma rota e a falha é claramente do callback, a conexão provisória e os registros criados apenas para aquela tentativa são removidos.

4. O assinante corrige e tenta novamenteO número não deve permanecer no painel como “Processando”, “Encerrado” ou “Erro” quando a limpeza é confirmada.

Mensagem em português

Depois da limpeza, o painel explica o motivo provável e orienta a corrigir a URL antes de iniciar uma nova conexão.

Quando a Meta pode ter aplicado a rota

Se houver timeout depois de uma possível escrita ou divergência na leitura posterior, a HookCloud encerra as tentativas, mas não apaga o estado às cegas. Atualize o painel e confira a conexão antes de tentar novamente.

Número já existente no Flow

Quando o ativo já pertence a outro workspace, o Flow pode pedir confirmação de transferência. A conexão anterior só é arquivada depois de verificar o número e a rota nova. Em WABA com vários números, uma transferência parcial pode ser bloqueada para não redirecionar os demais.

Não faça durante o processamento

não repita o Embedded Signup;
não inicie uma segunda conexão antes de ler a mensagem final em português;
não remova a parceria na BM sem orientação;
não altere o webhook em outra aba;
não desconecte a conexão de origem manualmente;
não envie o token ao suporte.

Quando escolher Chatwoot

Você não precisa preencher “Link do seu webhook”. Conclua a Meta, copie Phone Number ID, WABA ID e Meta Access Token, crie a inbox e clique em Verificar Chatwoot. É necessário ter assinatura ativa; não é necessário criar App próprio nem ser Tech Provider.

Consulte o guia completo de Chatwoot e plataformas externas.

Quando o destino é um CRM próprio

Escolha webhook próprio. Depois que a rota for confirmada, a Meta entrega os eventos operacionais ao endpoint informado e o CRM utiliza o Phone Number ID e o token para responder pela Graph API.

Sem construtor de funis interno

O HookCloud Flow atual não executa funis, tags, variáveis ou um bloco “Webhook/API”. Essas automações devem permanecer no CRM, n8n, Make ou backend do assinante.

Abrir o guia técnico de integração com CRM →

Erros comuns dentro da janela da Meta

Se a conexão falhar ainda dentro do Embedded Signup, consulte a aba visual com 8 erros comuns antes de repetir o processo.

Falhou antes do card aparecer?

Quando o erro acontece dentro da janela da Meta, muitas vezes a causa está em permissões, Business Portfolio, elegibilidade do número, bloqueio de pop-up ou uso do número em outro ativo.

Abrir erros comuns de conexão na janela da Meta →

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.