Preparar a conta Meta para o WhatsApp oficial

Ao fim desta página você tem cinco credenciais na mão e um número de WhatsApp registrado na Cloud API, pronto para ser conectado no HorusBI.

Todo o trabalho acontece no ambiente Meta da sua empresa. O número, a conta e a fatura ficam com você: a Meta cobra as conversas direto no seu cartão, sem intermediário e sem repasse.

Os títulos abaixo seguem a numeração que o próprio console da Meta usa, para você conseguir se localizar na tela enquanto lê.

Por que o aplicativo é seu, e não o do HorusBI

A Meta separa quem opera a própria conta de quem opera a conta dos outros. Um aplicativo que acessa contas de terceiros precisa de uma aprovação chamada Advanced Access, que envolve revisão com vídeo e prazo da Meta.

Quando o aplicativo é seu e a conta é sua, nada disso se aplica. Você cria o app no seu ambiente, gera o token no seu Gerenciador de Negócios e entrega essas credenciais ao HorusBI, que passa a falar com a Meta em nome da sua conta. Sai mais rápido e o controle continua com você: revogar o acesso do HorusBI é apagar o usuário do sistema que gerou o token.

Antes de começar

Você precisa de:

• Um Portfólio Empresarial no Gerenciador de Negócios. A verificação dele não trava o começo, ela é a Etapa 3 lá no fim, mas leva dias na fila da Meta, então convém abrir cedo.
• Um número de telefone livre, sem WhatsApp ativo. Esta é a parede mais comum do processo todo, e ela aparece no passo 3. Leia a seção abaixo antes de escolher o número.
• Um cartão de crédito para cadastrar na conta de WhatsApp.
• Uma URL de Política de Privacidade. Ela é obrigatória para publicar o aplicativo no passo 6, e sem publicar não chega mensagem nenhuma de volta.
• Acesso de administrador ao Portfólio Empresarial.

O número precisa estar livre

Se o número já tem WhatsApp, o console recusa com "Esse número de telefone já está registrado em uma conta do WhatsApp". Três saídas, e elas custam coisas diferentes:

Saída	Custo
Usar outro número sem WhatsApp	Nenhum. É a saída limpa.
Excluir a conta do número atual	Perde o histórico de conversas e sai de todos os grupos. Irreversível.
Manter número e histórico	Exige o fluxo de Coexistence, que só existe dentro do Embedded Signup e depende de aprovação da Meta. Não é possível neste caminho.

Para excluir a conta: no celular, WhatsApp › Configurações › Conta › Excluir minha conta. A liberação leva até três minutos.

Se o número atende cliente hoje, pare e escolha outro. Apagar histórico de atendimento para ganhar uma tarde é troca ruim, e o histórico não volta.

WARNING

Linha fixa verifica só por chamada de voz. O pedido por SMS retorna sucesso e o código nunca chega. Se o número for fixo, escolha voz já na primeira tentativa: depois de uma falha a Meta bloqueia novas tentativas por cerca de uma hora, em qualquer canal.

1. Criar o aplicativo e escolher o caso de uso

1. Entre em developers.facebook.com/apps com a conta que administra o Portfólio Empresarial.
2. Clique em Criar aplicativo.
3. Dê um nome ao app (algo como Conector WhatsApp) e vincule ao seu Portfólio Empresarial.
4. Em casos de uso, marque Conectar-se com clientes pelo WhatsApp.
5. Aceite os Termos de Serviço da Plataforma do WhatsApp Business.

O console pede casos de uso, não produtos. Guias mais antigos mandam "adicionar o produto WhatsApp", e essa tela não existe mais.

TIP

Se o app já existe e a tela diz Sem casos de uso neste app, clique em + Adicionar casos de uso e marque o mesmo item. Não precisa recriar o app.

Na tela de aceite dos termos, confira o portfólio selecionado. É ele que vai ser dono da conta de WhatsApp, e uma conta pertence a um portfólio só: mover depois dá trabalho.

Guarde o App ID, que aparece no topo do painel. Com ele você chega direto na página das credenciais, sem navegar:

https://developers.facebook.com/apps/<SEU_APP_ID>/settings/basic/

Lá, clique em Mostrar ao lado de Chave Secreta do Aplicativo e guarde o App Secret. O Facebook pede a senha de novo antes de revelar.

NOTE

O App Secret não é o token do passo 5, e os dois não se substituem. O token envia mensagens em nome da sua conta. O App Secret confere que as mensagens que chegam vieram mesmo da Meta e não de outra pessoa, porque o endereço que as recebe é público. Sem o token, nada sai. Sem o App Secret, nada entra.

2. Pular a Etapa 1

O console oferece três etapas. A Etapa 1, Experimente manda uma mensagem de um número de teste que a Meta empresta, e não serve para o que você quer.

Pior: ela cria uma conta de WhatsApp separada, só de teste. O diagrama de ativos do próprio console mostra as duas lado a lado:

Portfólio empresarial
├── Testar conta do WhatsApp Business (WABA)   ← Etapa 1
└── Sua conta do WhatsApp Business (WABA)      ← Etapa 2

Os identificadores que aparecem na Etapa 1 são da conta descartável. Copiar o de lá é o tipo de erro que só aparece três dias depois, quando nada chega.

Vá direto para a Etapa 2, Configuração da produção.

3. Etapa 2: adicionar o número

1. Clique em Adicionar número de telefone.
2. Informe o número, o nome de exibição e a categoria da empresa.
3. Escolha o método de verificação. Para linha fixa, chamada de voz; para celular, SMS serve.
4. Digite o código recebido.
5. Defina o PIN de seis dígitos quando pedido. Ele vira a verificação em duas etapas do número, e sem ele o número não envia nada.

O nome de exibição passa por aprovação da Meta e é o que seus clientes veem no WhatsApp. Use o nome comercial da empresa, porque nome genérico costuma ser reprovado.

Anote o PIN. Sem ele não dá para migrar o número depois, e recuperá-lo dá trabalho.

IMPORTANT

O WABA ID e o Phone Number ID aparecem juntos nesta tela. São números diferentes, e trocar um pelo outro é o erro mais comum na hora de conectar. Confira que são os da sua conta, não os da conta de teste da Etapa 1.

4. Etapa 2: cadastrar o meio de pagamento

Ainda na Etapa 2, adicione um cartão de crédito à conta de WhatsApp.

Sem cartão a conta fica no limite de teste, que permite mensagens só para cinco números cadastrados manualmente. É a causa número um de "funciona no teste e não funciona com cliente de verdade".

5. Etapa 2: criar o usuário do sistema e gerar o token

Este é o passo que entrega o acesso ao HorusBI. O token precisa vir de um usuário do sistema, porque token de pessoa expira quando a pessoa troca de senha ou sai da empresa.

1. Abra Configurações do negócio › Usuários › Usuários do sistema.
2. Clique em Adicionar, dê um nome (algo como horusbi-api) e escolha o papel Administrador.
3. Com o usuário selecionado, clique em Adicionar ativos, escolha Contas do WhatsApp, marque sua conta e conceda Controle total.
4. Clique em Gerar novo token.
5. Escolha o aplicativo que você criou no passo 1.
6. Em expiração, escolha Nunca.
7. Marque as permissões whatsapp_business_messaging e whatsapp_business_management.
8. Clique em Gerar token e copie o valor.

IMPORTANT

O token aparece uma única vez. Se fechar a janela sem copiar, gere outro. Trate esse valor como senha: quem tem o token envia mensagem em nome da sua empresa.

Se o token for gerado contra um aplicativo diferente do que você criou no passo 1, ele não consegue ler a sua conta e a conexão é recusada com erro de permissão. Confira o nome do app na tela antes de gerar.

6. Publicar o aplicativo

Aplicativo em modo de desenvolvimento só recebe webhook de teste. Nenhum dado de produção chega, e o console avisa isso em laranja na tela de webhooks.

Na prática: sem publicar, o envio funciona e o recebimento não. Nem resposta de cliente, nem confirmação de entrega, nem aviso de template reprovado.

Em Configurações do aplicativo › Básico, preencha ícone, categoria e a URL de Política de Privacidade. Depois mude o app para o modo Ativo no topo do painel.

Publicar não exige App Review no caminho descrito aqui, porque o aplicativo só acessa a sua própria conta.

7. Etapa 3: verificação da empresa

Carregue os documentos da empresa para análise da Meta.

Isso pode correr em paralelo com tudo acima, e convém abrir cedo, porque o prazo é da Meta e não seu. Enquanto não sair, o número fica no limite de teste e não fala com cliente de verdade.

O que entregar ao HorusBI

Cinco valores:

Credencial	Onde achar
WABA ID	Etapa 2, na tela do número
Phone Number ID	Etapa 2, ao lado do WABA ID
Token permanente	Gerado no passo 5, visível uma única vez
App Secret	Configurações do aplicativo, Básico, botão Mostrar
App ID	Painel do app, no topo

O PIN de seis dígitos fica só com você. O HorusBI não precisa dele: quem registra o número na Cloud API é o dono da conta.

Você não precisa configurar o webhook. O HorusBI liga isso por API com o App ID e o App Secret, e assina os eventos de mensagem, status de entrega, mudança de categoria de template e queda de qualidade do número. Basta o aplicativo estar publicado, do passo 6.

Com isso em mãos, siga para Conectar o WhatsApp oficial no HorusBI.

Modos de falha conhecidos

Coisas que já quebraram em implantações reais, e como reconhecer cada uma.

• "Esse número já está registrado em uma conta do WhatsApp" — O número não está livre. Ver a seção "O número precisa estar livre", em Antes de começar.
• Erro 200 ao ler a conta — O token foi gerado contra o aplicativo errado, ou o usuário do sistema não tem a conta entre os ativos. Refaça o passo 5.
• Erro 133010 ao enviar — O número não foi registrado. Volte ao passo 3 e defina o PIN.
• Erro 132001 ao enviar — O template não existe nessa conta, ou o nome e o idioma não batem exatamente com o que foi aprovado.
• Envia mas nunca recebe — O aplicativo está em modo de desenvolvimento. Volte ao passo 6.
• As primeiras mensagens somem — Conta nova sem histórico costuma ter os primeiros envios descartados em silêncio, com resposta de sucesso da API. Peça para alguém mandar uma mensagem para o número primeiro: isso abre a janela de conversa e destrava o envio.
• Template aprovado vira MARKETING — A Meta reclassifica a categoria por conta própria depois da aprovação, e MARKETING custa cerca de três vezes mais que UTILITY. Template com anexo PDF no cabeçalho e texto curto no corpo se mantém como UTILITY. Corpo com texto livre ou cabeçalho de imagem quase sempre migra para MARKETING.
• Verificação bloqueada por uma hora — Depois de uma tentativa falha, a Meta recusa novos pedidos de código por cerca de sessenta minutos, mesmo trocando de canal. Espere, não insista.