Como conectar um número à API oficial do WhatsApp
Conectar é autorizar: o cliente entra com a conta Meta dele, escolhe o número que já usa e confirma no celular. Não há QR code, não há sessão para cair e o número continua no aplicativo WhatsApp Business.
Antes de começar
Três coisas precisam existir do lado do seu cliente. Nenhuma delas é criada pelo Hub — são contas da própria empresa dele, e é assim de propósito: o número, a conta e a fatura ficam com quem é dono do negócio.
- Uma conta comercial da Meta — se a empresa já anuncia no Facebook ou Instagram, ela existe. Se não, é criada durante o próprio processo de conexão.
- O número em mãos — quem estiver com o celular precisa confirmar a autorização ali, na hora.
- Verificação de negócio, quando exigida — a Meta pede documento da empresa em parte dos casos. É a etapa mais lenta, e a única que pode levar dias em vez de minutos.
Os passos
O caminho abaixo é o de coexistência, que é o que a maior parte das operações quer: o número segue no aplicativo e passa a responder pela API ao mesmo tempo.
- 1. Abrir a conexão no painel — em
/painel, criar um canal. O Hub abre o Embedded Signup da Meta em uma janela, com as permissões já declaradas. - 2. O cliente entra com a conta Meta dele — é a conta da empresa, não a sua. Quem autoriza é o dono do número.
- 3. Escolher o número que já está em uso — a janela lista os números do aplicativo WhatsApp Business daquela conta. Selecionar o número que a empresa já divulga é o ponto inteiro da coexistência.
- 4. Confirmar no celular — o aplicativo pede a confirmação da vinculação. É aqui que o número em mãos importa.
- 5. Aguardar o canal ficar ativo — o Hub recebe o retorno da Meta, registra o canal e emite o token daquele número. A partir daí, envio e webhooks funcionam.
O que muda depois de conectado
Do lado do cliente, quase nada — e essa é a proposta. Ele continua atendendo pelo celular quando quiser. Do lado do seu sistema, três coisas passam a existir:
- Envio programático — mensagens de template para iniciar conversa e mensagens livres dentro da janela de atendimento.
- Webhooks assinados — cada mensagem recebida chega ao seu endpoint com assinatura HMAC, incluindo o eco do que o cliente digitou no celular.
- Qualidade e limite por número — a Meta passa a classificar a qualidade daquele número e a definir quantas conversas ele pode iniciar por dia. É o substituto do risco de banimento, e é um sinal que dá para acompanhar.
Perguntas frequentes
Preciso de um número novo para usar a API oficial do WhatsApp?
Não, se a conexão for por coexistência. O número que já está no aplicativo WhatsApp Business é autorizado na Cloud API e continua funcionando no celular do cliente, com o histórico intacto. Um número novo só é necessário quando o cliente opta por dedicar o número à API e abrir mão do aplicativo.
O cliente perde o histórico de conversas ao conectar na API oficial?
Na coexistência, não. As conversas permanecem no aplicativo, e as mensagens que chegam ou saem por lá são espelhadas para o seu sistema como evento de eco. Na conexão dedicada, o número sai do aplicativo e o histórico não é migrado.
Quanto tempo demora para conectar um número?
A autorização em si leva alguns minutos: o cliente percorre o Embedded Signup, escolhe o número e confirma no celular. O que costuma demorar é o que vem antes — ter uma conta comercial da Meta e concluir a verificação de negócio, quando ela é exigida.
Posso conectar o número lendo um QR code?
Não na API oficial. QR code é como as integrações não oficiais abrem uma sessão do WhatsApp Web. A Cloud API autoriza o número pela conta Meta da empresa, uma vez, e não mantém sessão de navegador nenhuma — por isso ela não cai e não precisa ser relida.