Passo a passo pra conectar seu número de WhatsApp à API oficial da Meta (Cloud), incluindo verificação, escolha de número e o que pode dar errado no caminho.
O que você vai precisar antes de começar
- Conta no Facebook Business Manager com sua empresa cadastrada. Não é o Facebook pessoal — é o Business.
- Número de telefone que NÃO está em uso no WhatsApp comum (nem Web, nem Business app). Se estiver, a Meta vai pedir pra remover antes.
- Permissão de administrador no Business Manager.
- CNPJ ou documento da empresa caso a Meta peça verificação adicional.
Como funciona o setup
O Codewo conversa com a Meta via Embedded Signup — uma janela popup oficial da Meta que cuida da autenticação, escolha de WABA (WhatsApp Business Account) e seleção de número. Você não digita Access Token na mão; ele vem da Meta automaticamente.
Passo a passo
Em Configurações → Canais → Novo canal → WhatsApp Cloud:
- Clique em "Conectar com Meta" — Abre o popup da Meta. Faça login com a conta administradora do Business Manager.
- Escolha o Business — Se você tem mais de um Business cadastrado, selecione qual vai usar.
- Escolha ou crie o WABA — Se ainda não tem um WhatsApp Business Account, a Meta cria na hora. Se já tem, selecione.
- Escolha o número de telefone — Pode ser um número novo (a Meta envia código de verificação por SMS ou ligação) ou um existente.
- Verifique o número — Insira o código que chegar no celular. Esse passo é da Meta, não do Codewo.
- Defina o nome de exibição (Display Name) — É o nome que aparece no perfil do WhatsApp pro cliente.
- Volte ao Codewo — A janela fecha automaticamente. Dê um nome interno ao canal (ex: "WhatsApp Vendas") e escolha a equipe que vai receber as conversas.
- Salve. O canal já está ativo.
Pegadinhas comuns
- "Competing BSPs" — esse é o erro mais comum. Se o número já está conectado a outra ferramenta (provedor de WhatsApp Cloud), a Meta avisa que existe BSP concorrente. Você precisa remover o BSP antigo no painel da Meta antes de seguir, senão webhooks duplicam e mensagens se perdem.
- Janela de 24 horas — Depois que o cliente para de responder por 24h, você só consegue falar de novo com ele via template HSM aprovado. Se tentar mandar mensagem livre, o Codewo marca a conversa como "sessão fechada" e bloqueia novos envios livres até o cliente responder.
- Número precisa estar "limpo". Se você usava esse número no WhatsApp Web ou no app Business, precisa desinstalar/sair de todas as sessões antes. Senão a verificação Meta falha.
- Display Name passa por revisão. A Meta valida o nome (não pode ser genérico tipo "WhatsApp", não pode conter palavrões, não pode prometer regulamentação). Se reprovar, você vê o motivo no painel da Meta — Codewo só repassa o status.
- Áudio gravado no navegador exige formato OGG/Opus. Mensagens de voz gravadas no Codewo são convertidas antes de mandar — se a conversão falhar (ex: bug no navegador), o áudio vira anexo comum. O cliente recebe mas como arquivo, não como voice note tocável inline.
- Access Token vive 60 dias. O Codewo renova automaticamente quando possível, mas se a sua conta Meta tiver problema (senha mudou, 2FA disparou), o token pode expirar e o canal fica offline. Dá pra reconectar sem perder histórico — basta refazer o Embedded Signup.
Boas práticas
- Use número dedicado — Não compartilhe o número entre WhatsApp Cloud e celular pessoal de funcionário. Se a pessoa sair, o número fica.
- Cadastre templates HSM cedo — Aprovação leva 24–72h. Tenha pelo menos um template de notificação ("seu pedido foi enviado") aprovado antes de precisar.
- Configure equipe ANTES de divulgar — Conecte o canal, defina pra qual equipe vão as conversas, então comece a divulgar.
- Defina horário de atendimento — Sem isso, SLA conta 24/7 (ver Horários de atendimento).