Como começar na API oficial do WhatsApp (Cloud API da Meta) e que número usar?
Por NumioPublicado em
A API oficial do WhatsApp é a Cloud API, da plataforma WhatsApp Business da Meta: uma API HTTP, hospedada pela própria Meta, pela qual um sistema envia e recebe mensagens num número de telefone. É por ela que se conectam CRMs, chatbots, agentes de IA e ferramentas de automação. A versão instalada em servidor próprio (On-Premises) foi encerrada em 23 de outubro de 2025, então hoje API oficial e Cloud API são a mesma coisa.
Pra começar você precisa de cinco coisas: uma conta empresarial na Meta, um app com o produto WhatsApp, uma conta do WhatsApp Business (WABA), um token e um número de telefone que não esteja em uso no WhatsApp e que receba o código de verificação. O número não precisa ser celular: a Meta aceita número fixo e número virtual, verificados por ligação de voz em vez de SMS.
É essa a parte que a Numio resolve. O número fixo virtual da Numio (R$ 25,90/mês, ou R$ 16,90/mês no anual) recebe a ligação da Meta, atende sozinho e mostra o código no painel. Depois de registrado, ele funciona na API como qualquer outro número. A plataforma que envia as mensagens é escolha sua.
O que é preciso ter pra usar a API oficial do WhatsApp?
| Item | Onde se cria | Pra que serve |
|---|---|---|
| Conta empresarial (portfólio) | Meta Business Suite | É a dona dos números, dos limites de envio e da cobrança |
| App com o produto WhatsApp | Meta for Developers | Dá acesso à Graph API e recebe os webhooks |
| Conta do WhatsApp Business (WABA) | Criada junto com o app | Agrupa os números e os templates de mensagem |
| Token de usuário do sistema | Configurações da conta empresarial | Autentica as chamadas; não expira como o token de teste |
| Número de telefone | Você traz | É o remetente. Precisa estar livre e receber o código |
| Webhook (URL pública com HTTPS) | No seu servidor ou na sua ferramenta | Recebe as mensagens que chegam e os avisos de entrega |
A verificação da empresa (envio de documentos, CNPJ) não é exigida pra mandar a primeira mensagem, mas é ela que aumenta os limites da tabela mais abaixo e libera o nome de exibição.
Que número de telefone a API oficial aceita?
Pela documentação da Meta (lida em 13 de outubro de 2026), o número precisa ser seu, ter código de país e de área e conseguir receber ligação de voz ou SMS. Número que já está em uso no WhatsApp só entra depois de a conta ser apagada no app.
| Tipo de número | Código por SMS | Código por ligação | O que a Meta pede |
|---|---|---|---|
| Celular | Sim | Sim | É o tipo recomendado pela Meta |
| Fixo | Não recomendado | Padrão | Linha pronta pra receber ligação internacional, sem desvio de chamada nem URA na frente |
| VoIP (número virtual) | Não recomendado | Padrão | Que o provedor aceite ligação internacional pro código |
| Número curto (short code) | Não aceito | Não aceito | Precisa ter código de país e de área |
Um número registrado na API continua servindo pra ligações comuns, mas sai do app do WhatsApp: o mesmo número não fica no app e na API ao mesmo tempo, salvo no modo de coexistência, que só existe por provedor oficial.
A Numio fornece o número e entrega o código de verificação. Envio de mensagens, templates, webhook, token e cobrança por mensagem são da Meta (ou do provedor oficial que você escolher). O número é fixo: não recebe SMS.
Devo usar o número de teste da Meta ou um número próprio?
Ao criar o app, a Meta gera uma conta de teste e um número de teste. Ele serve pra validar a integração: tem limites de envio folgados e manda template sem forma de pagamento cadastrada. Mas é um número da Meta, com nome genérico, e os seus clientes não o reconhecem.
Pra produção você registra um número seu. Vale separar: um número próprio só pra homologação, que pode ser bloqueado por um template ruim sem derrubar o atendimento, e outro pro ar. Na Numio dá pra contratar os dois no mesmo pedido.
Como o número é verificado e registrado?
1. Contrate o número
Em escolher número, escolha o DDD, pague e valide a identidade do titular. O número fica pronto no mesmo dia. Não ative ele no app do WhatsApp.
2. Adicione o número na conta do WhatsApp Business
Pelo WhatsApp Manager, pelo fluxo da sua ferramenta ou direto pela Graph API. Informe o número com +55 e o nome de exibição.
3. Peça o código por ligação de voz
Na etapa de verificação, escolha ligação, não SMS. A Meta liga, a Numio atende e o código de 6 dígitos aparece no painel e no seu e-mail.
4. Digite o código e registre
Com o código confirmado, o número é registrado com um PIN de 6 dígitos, que vira a verificação em duas etapas dele.
5. Aponte o webhook e mande a primeira mensagem
Assine o campo
messagesno webhook do app, gere o token de usuário do sistema e envie um template de teste pro seu celular.
Quem prefere fazer por código tem as quatro chamadas, com curl, em registrar número por API. Quem prefere pedir a um agente de IA tem o MCP da Meta.
Quais são os limites de uma conta nova?
| Limite | Conta nova | Depois de verificar a empresa |
|---|---|---|
| Números registrados por conta empresarial | 2 | 20 (sobe sozinho) |
| Clientes diferentes que recebem template em 24 horas | 250 | 2.000, depois 10.000, 100.000 e sem limite |
| A quem o limite de envio pertence | À conta empresarial, dividido entre os números | Idem |
| Mensagens por segundo, por número | 80 | 80 |
O ponto que mais confunde: o limite de envio é da conta empresarial, não do número. Ter mais números não multiplica o limite. Mais números servem pra separar operações (um por marca, por filial, por cliente, por ambiente) e pra isolar risco. Na Numio você contrata até 20 números por pedido.
Quanto custa usar a API oficial do WhatsApp?
São duas contas separadas. O uso da API é cobrado pela Meta, direto de você, por mensagem, conforme a tabela publicada no site dela. O número é cobrado pela Numio, com preço fixo por mês, sem cobrança por mensagem e sem taxa de ativação.
| Período | Valor cobrado | Equivalente por mês | Economia vs. mensal | Inclui |
|---|---|---|---|---|
| Mensal | R$ 25,90 por mês | R$ 25,90/mês | — | Número exclusivo, suporte humano, 7 dias de garantia |
| Trimestral | R$ 62,70 a cada 3 meses | R$ 20,90/mês | 19% | Número exclusivo, suporte humano, 7 dias de garantia |
| Anual | R$ 202,80 por ano | R$ 16,90/mês | 35% | Número exclusivo, suporte humano, 7 dias de garantia, 1 troca de número grátis |
Preciso de um provedor oficial (BSP) ou posso ir direto na Meta?
Pode ir direto. A Cloud API é aberta a qualquer empresa, e o cadastro é feito no Meta for Developers. O provedor oficial (hoje a Meta chama de parceiro de soluções ou provedor de tecnologia) entra quando você quer caixa de entrada pronta, suporte em português, cobrança em uma fatura só ou o modo de coexistência com o app.
Nos dois caminhos o número é verificado do mesmo jeito, por SMS ou por ligação. A Numio não é um provedor oficial de mensagens: fornece o número e entrega o código. Mais sobre isso em número virtual pra API do WhatsApp.
Guias desta seção
- Registrar o número por chamada de APIAs quatro chamadas da Graph API, com curl, e o código chegando por webhook.
- Número pra agente de IA no WhatsAppComo o agente se liga ao número e o que a Meta permite.
- API oficial ou não oficialCloud API, Evolution API, Baileys e Z-API: diferença, risco e que número pôr em cada uma.
- n8n na API oficial do WhatsAppO que o n8n pede e como registrar o número. Também Chatwoot, Typebot, Make e Botpress.
- Um número por cliente da sua plataformaPra SaaS e agências: contratar números por API e entregá-los já verificados.
- MCP do WhatsApp BusinessConfigurar a Cloud API conversando com Claude, ChatGPT ou Codex.
Perguntas frequentes
É a Cloud API, da plataforma WhatsApp Business da Meta. A versão On-Premises, instalada em servidor próprio, foi encerrada em 23 de outubro de 2025.
Aceita. A documentação da Meta lista número fixo e VoIP com verificação por ligação de voz como padrão. O número precisa estar livre no WhatsApp e receber ligação internacional sem URA na frente.
Não ao mesmo tempo, salvo no modo de coexistência, oferecido só por provedores oficiais e com limitações. Fora dele, um número registrado na API sai do app.
Uma conta empresarial nova registra 2 números. Depois de verificar a empresa, ou ao chegar ao limite de envio de 2.000, a Meta sobe o teto pra 20 automaticamente.
Não. O limite de envio é da conta empresarial e é dividido entre todos os números dela. Começa em 250 clientes diferentes por 24 horas e sobe pra 2.000, 10.000, 100.000 e sem limite.
Não. A Numio fornece o número fixo virtual e entrega o código de verificação. O envio de mensagens é feito pela Cloud API da Meta, direto ou por um provedor oficial.
Pra verificar a empresa na Meta e sair dos limites iniciais, sim. Pra contratar o número na Numio, não: pessoa física também pode.