Conectar pela API Oficial da Meta

O que muda ao entrar na API Oficial

É o caminho indicado, de risco menor — não zero: a Meta também restringe e bane número por violação de política. O que você ganha é regra publicada e aviso antes da queda. Em troca:

1. O número sai do aplicativo comum do WhatsApp. Ninguém mais abre aquele número no celular pra responder. Use chip novo ou número dedicado ao atendimento.
2. Você não puxa assunto livremente. A Meta só deixa a empresa iniciar conversa com um template aprovado. Depois que o cliente responde, abrem 24 horas de conversa livre.

O comparativo com a Z-API está em WhatsApp: API Oficial ou Z-API?.

Visão geral

O guia completo fica em /settings/whatsapp/guia-meta (o formulário de conexão Meta linka pra ele no box "Onde encontro essas informações?"). Leva uns 25 minutos e não exige conhecimento técnico.

Você vai pegar 4 credenciais no painel da Meta (Token de acesso, Phone Number ID, WABA ID e Chave secreta do app), configurar pagamento, webhook e template, e colar tudo no CRM.

Pré-requisitos: conta Facebook/Meta (a pessoal serve, ela só administra), perfil admin na Conta Comercial (Meta Business), número dedicado com acesso a SMS ou ligação, e cartão de crédito internacional (a Meta cobra em dólar).

Os 7 passos

1. Criar o app: developers.facebook.com/apps → Criar aplicativo → caso de uso "Conectar-se com clientes pelo WhatsApp". O caminho-chave: Casos de uso → Personalizar → Etapa 2 · Configuração de produção — é onde ficam número, pagamento e webhook.
2. Phone Number ID e WABA ID: business.facebook.com → Configurações do Negócio → Contas → Contas do WhatsApp (o WABA ID fica em "Identificação"). Depois, Gerenciador do WhatsApp → Números de telefone → clique no número (aparece o Phone Number ID). São identificadores, não senhas.
3. Token permanente: Configurações do Negócio → Usuários → Usuários do Sistema → Adicionar (função Administrador) → Atribuir ativos: o APP (Gerenciar app) e a CONTA DO WHATSAPP (Acesso total). Esquecer a conta gera um token que não envia mensagem. Gere o token com validade Nunca e permissões whatsapp_business_messaging + whatsapp_business_management. O token aparece uma única vez (começa com EAAG...) — copie na hora.
4. Pagamento: business.facebook.com → Cobrança e pagamentos → Contas do WhatsApp Business → Adicionar forma de pagamento (cartão em dólar). Sem isso as mensagens não saem depois do teste. É o passo que mais trava gente.
5. Webhook (a ordem importa):

• Primeiro crie e salve o canal no CRM (Conectar novo número → Meta Cloud API), definindo o Webhook Verify Token — uma senha que você inventa, com 8 caracteres ou mais.
• Depois, na Meta (Casos de uso → Personalizar → Etapa 2 → Configurar webhooks): URL de callback = https://crmdojordao.com.br/api/webhooks/whatsapp/meta · Verificar token = o mesmo que você digitou no canal do CRM → Verificar e salvar.
• Ative dois campos na lista do webhook: messages (mensagens recebidas e confirmações de entrega) e message_template_status_update (avisa o CRM na hora em que a Meta aprova um modelo).
• A verificação falha se o canal ainda não foi salvo no CRM, ou se URL/token foram colados com espaço ou diferentes.
• Chave secreta do app: no app da Meta, Configurações do app → Básico → Chave secreta do aplicativo → Mostrar (32 caracteres). É com ela que a Meta assina cada webhook, e o CRM confere essa assinatura pra saber que a mensagem veio mesmo dela. Sem a chave o CRM recusa tudo que chega — você não vê "entregue" e as respostas dos seus clientes não aparecem no Inbox.

1. Template de abertura: Gerenciador do WhatsApp → Modelos de mensagem → Criar modelo. Nome em minúsculas_com_underscore, Português BR, categoria Marketing ou Utilidade, use {{1}} pra personalizar.
2. Colar no CRM: telefone em formato E.164 + Phone Number ID + WABA ID + Access Token + Chave secreta do app + Webhook Verify Token → salvar → mande uma mensagem de teste pro seu próprio número e responda dele. Chegou lá e a resposta apareceu no Inbox: está no ar nos dois sentidos.

Erros comuns

• Webhook não verifica (sem check verde): o canal não foi salvo no CRM antes, ou a URL/token foram colados com espaço ou diferentes.
• "Token inválido" ou mensagens pararam: você usou o token temporário, que expira em 24h. Refaça o passo 3 com Usuário do Sistema e validade Nunca.
• Não consegue iniciar conversa: a primeira mensagem precisa ser um template aprovado (passo 6).
• Mensagens não saem mesmo com tudo certo: quase sempre é pagamento (passo 4) — cartão não vinculado ou recusado.
• O envio sai, mas nenhuma resposta chega (e nunca aparece "entregue"): falta a chave secreta do app no canal, ou ela foi colada errada. O CRM recusa webhook sem assinatura válida, então a volta fica muda. A tela de Canais de WhatsApp avisa quando é esse o caso — abra Editar no canal e cole a chave.
• O modelo está aprovado na Meta mas o CRM diz que não está: assine o campo message_template_status_update (passo 5) pra receber o aviso na hora. De qualquer forma o CRM confere com a Meta no momento do envio, então basta tentar de novo.
• Códigos da Meta: 131049 e 131056 (limite/volume de marketing — use categoria Utilidade e reduza a frequência), 130472 ("experimento" da Meta — use template de Utilidade ou aguarde o cliente iniciar), 131042 (falha no pagamento), 131026 (o destino não tem WhatsApp).
• Número aparece "Conectado" no CRM, mas não manda nem recebe nada de verdade (e no Gerenciador do WhatsApp → Números de telefone o status dele está "Pendente", ou a Meta acusa "falta fazer API de registro" ao abrir o número): o CRM já tenta registrar o número na Cloud API sozinho, logo depois de salvar o canal. Se essa tentativa falhar, a tela de Canais de WhatsApp mostra um aviso direto no card do canal explicando o motivo — geralmente "número já registrado antes" (inofensivo, ignore) ou um erro real da Meta que precisa investigar. Abra Editar e salve de novo (mesmo re-colando o mesmo Access Token) pra tentar o registro outra vez.

Etapas complementares (quando a Meta pedir)

• Verificação do negócio: Configurações do Negócio → Centro de Segurança → Começar verificação (CNPJ + comprovante de endereço, até 48h úteis). Libera limites maiores de envio.
• Nome de exibição: Gerenciador do WhatsApp → Números de telefone → engrenagem → Perfil → Nome de exibição. Passa por aprovação da Meta e precisa ser coerente com a marca.
• Nota de qualidade (Verde/Amarelo/Vermelho) no Gerenciador: sobe quando as pessoas respondem, cai com bloqueios e denúncias. Nota alta significa mais mensagens liberadas por dia.