Escolha o destino das mensagens
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.
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.
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. |
Qual opção escolher na seleção de telefone?
Antes de avançar, identifique onde o seu número está hoje: no WhatsApp do celular, no WhatsApp Business, em uma conta empresarial da Meta ou em outro provedor de API. A janela pode reunir essas escolhas em uma mesma tela; os textos e as opções disponíveis variam conforme a conta e o fluxo.
| Opção ou estado | Como interpretar | Próximo passo |
|---|---|---|
| Insira um novo número de telefone | Permite informar o telefone que será usado no caminho apresentado pela Meta. Não é uma ordem para recriar todo número existente. | Se houver um número existente elegível, selecione o ativo correto. Se o caminho adequado pedir digitação, informe o telefone pretendido com DDI. Confirme a modalidade nas etapas seguintes; o nome dessa opção não comprova migração ou coexistência. |
| Usar um nome de exibição com um número virtual | Quando disponível, é a oferta de um novo número pela Meta. Não conecta o seu telefone atual nem ativa coexistência. | Leia as condições da Meta. A opção não garante, sozinha, que o restante da integração HookCloud será concluído. |
| Número existente · Registrado | É um estado exibido pela Meta. Não confirma autorização, callback ou conclusão da conexão na HookCloud. | Se a Meta permitir selecionar o ativo correto, revise o telefone e prossiga. Depois confira o resultado no painel HookCloud. |
| Não qualificado | O ativo não está disponível para essa escolha naquele momento; o rótulo isolado não explica a causa e não significa necessariamente banimento. | Leia o detalhe ou código apresentado e consulte o roteiro de elegibilidade. Não exclua o número nem crie outra empresa apenas para tentar novamente. |
Se você quer manter o WhatsApp Business no celular, use a opção de coexistência quando ela estiver disponível e o número for elegível. Esse fluxo pode pedir que você informe o telefone existente e confirme a conexão no aplicativo; selecionar uma linha na lista não é uma regra universal. Não apague a conta do celular para tentar habilitar coexistência. Fonte: Meta — conectar usuários do WhatsApp Business.
Um número ausente da lista não comprova que pertença a outra empresa ou a outro parceiro. A Meta está implantando uma experiência que recebe o telefone antes da escolha dos ativos e pode iniciar a coexistência automaticamente quando ela está habilitada e reconhece um número do Business App. Outras contas ainda veem a ordem anterior. A aparência da tela não confirma, sozinha, qual configuração foi usada nesta tentativa. Confira o fluxo atual documentado pela Meta.
Se uma etapa posterior pedir remoção ou desconexão, confira qual vínculo a mensagem menciona e seu impacto antes de agir. Se aparecer 2494064, veja número já registrado e o aviso de até 3 minutos. Não exclua a conta do celular, o telefone ou uma WABA para testar.
Se aparecer “Não qualificado”, consulte a imagem ilustrativa e o roteiro para verificar o motivo. Esse selo não é uma classificação de banimento ou RED, não comprova falha de callback e não significa revisão automática pela HookCloud. Se o número nem aparece na lista, confira perfil, WABA e modalidade.
O portfólio ou a empresa não aparece
Business Portfolio é o portfólio empresarial da Meta; WABA é a conta do WhatsApp Business dentro dessa estrutura. A escolha pode estar integrada a outra tela ou já preenchida. A ausência de uma etapa separada não prova que os ativos foram perdidos.
- Confira qual perfil Facebook ou credencial empresarial está conectado na janela da Meta. Use a identidade que recebeu acesso aos ativos do cliente.
- Abra o Meta Business Suite e confirme a empresa, a conta WhatsApp e as permissões administrativas ou de controle necessárias.
- Compare o Business ID e a WABA esperados com os ativos disponíveis. Se faltar acesso, peça ao administrador responsável a permissão correta.
- Se aparecer o código
1690114, pare a criação de novos negócios e consulte o diagnóstico desse limite.
A Meta documenta seleção de ativos existentes, telas reduzidas por dados previamente preenchidos e critérios próprios para cada fluxo: fluxo padrão e experiência de seleção de ativos v4. A aparência da sua tela, por si só, não confirma a versão usada pela integração.
Tipos de conexão
| Modo | Quando usar | Cuidados |
|---|---|---|
| Coexistência com WhatsApp Business | Manter o aplicativo WhatsApp Business e conectar o mesmo número à plataforma, quando o fluxo estiver disponível e o número for elegível. | Siga a confirmação solicitada no aplicativo. Mantenha-o atualizado; não exclua a conta para tentar habilitar esse modo. |
| Cloud API com número próprio | Usar o número na plataforma oficial pelo caminho de cadastro ou migração indicado. | Confirme o vínculo atual e o impacto antes de migrar. WhatsApp pessoal, Business App e número já em outro provedor são situações diferentes. |
| Número fornecido pela Meta | Usar um novo número disponibilizado pela própria Meta, quando oferecido. | Leia as condições e confira se a conexão foi concluída pela HookCloud. A oferta na janela não transforma seu número atual em coexistência. |
Veja as diferenças na orientação oficial de migração e no guia oficial de coexistência.
Botão “Conectar com a Meta”
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.
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.
Timeout por validação
Cada chamada de validação do callback pode aguardar até 10 segundos antes de ser classificada.
O que acontece quando o webhook está errado
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.
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.
Na primeira tentativa, pode ainda não existir um registro de conexão na HookCloud se a autorização não foi concluída. A ausência desse registro não invalida a mensagem exibida pela Meta. Use o código, a etapa e o horário para conferir o ocorrido, sem exigir um Connection ID que ainda não foi criado.
Se o aviso mencionar acesso avançado do aplicativo, consulte a diferença entre o aplicativo da integração e o WhatsApp Business do celular.
Envie o e-mail do owner, Workspace ID e horário aproximado; inclua Connection ID e código de suporte se já tiverem sido criados no painel. Encaminhe essas informações para suporte@hookcloud.app. Nunca envie o token completo.