API oficial do WhatsApp: como usar, passo a passo para iniciantes

Para usar a API oficial do WhatsApp, você cria um app no painel de desenvolvedores da Meta ligado ao portfólio da sua empresa, registra um número, gera um token permanente e aponta o webhook para a plataforma de atendimento. Depois disso, as conversas chegam no sistema (no meu caso, o Chatwoot) e você passa a mandar templates aprovados para iniciar contato.

O caminho tem uns nove passos e nenhum é complicado sozinho. O que trava quem está começando é a ordem, os nomes que a Meta usa em cada tela e alguns erros que custam dias. Segui a documentação oficial da Meta para os nomes e completei com o que apareceu na live de lançamento do Tech Provider, gravada em junho de 2026 com o Nick Silva, que trabalha com aprovações na Meta há três anos.

Antes de começar: o que você precisa ter

Separe isso antes de abrir a primeira tela da Meta:

• CNPJ ativo e com dados atualizados. MEI serve.
• E-mail no domínio da empresa, não Gmail.
• Site no ar com HTTPS, com política de privacidade e termos de uso.
• Um número de telefone com código de país e DDD, que receba SMS ou ligação. A página de números da Meta recomenda número de celular para receber o código.
• Cartão para cadastrar como forma de pagamento, porque a Meta cobra por mensagem.
• Uma plataforma para atender. Sem ela, você só manda mensagem pela API, sem tela de conversa.

Se o número que você quer usar já está no WhatsApp do celular, decida agora: ou você apaga a conta do WhatsApp nesse número antes de registrar na API, como pede a documentação, ou usa a coexistência, que mantém o app funcionando junto com a API. A coexistência é feita pelo cadastro incorporado de uma plataforma aprovada pela Meta, não pela configuração manual.

Passo a passo da API oficial do WhatsApp

1. Portfólio empresarial (o antigo Business Manager)

Tudo na Meta fica pendurado num portfólio empresarial. Se você já anuncia no Facebook ou no Instagram, provavelmente tem um. Confira se o nome, o endereço e o telefone batem com o cartão do CNPJ. Na live, o Nick foi direto: a Meta cruza os dados, e informação diferente em cada lugar é o motivo mais comum de reprovação.

Uma dica que ele deu e eu reforço: se a sua conta de anúncios corre risco de bloqueio, não use o mesmo portfólio para o app. Bloqueio de anúncio não deveria derrubar o seu WhatsApp.

2. Conta de desenvolvedor e app na Meta

Faça o cadastro de desenvolvedor e, no Painel de Apps, crie um app. Na escolha do caso de uso, selecione Connect with customers through WhatsApp e vincule o portfólio da empresa. A Meta liga o app a uma conta do WhatsApp Business (a WABA, que a documentação nova chama de Messaging account).

3. Teste com o número que a Meta te dá

Na tela API Setup, a Meta gera um número de teste. Você escolhe esse número no campo From, coloca o seu celular no To, clica em Generate access token e manda a primeira mensagem. Serve para ver que tudo está ligado. Esse token é temporário e não serve para produção.

4. Token permanente com usuário do sistema

Nas configurações do negócio, em Usuários > Usuários do sistema, crie um usuário do sistema administrador, atribua a ele o app e a conta do WhatsApp com controle total e gere um token. A Meta pede as permissões business_management, whatsapp_business_messaging e whatsapp_business_management. No guia do Chatwoot, a orientação é escolher validade Nunca.

Guarde esse token como senha. Quem tem ele usa o seu WhatsApp.

5. Webhook

O webhook é o endereço para onde a Meta manda as mensagens recebidas e os status de entrega. Sem ele, você envia mas não recebe nada. O endereço precisa ter HTTPS válido.

Se você vai usar o Chatwoot, não precisa montar servidor de webhook: o guia de configuração manual do Chatwoot mostra que ele configura o webhook na Meta sozinho. Se a verificação falhar, você copia a URL do webhook e o token de verificação da aba de configuração da caixa e cola em WhatsApp > Configuração no app da Meta, assinando o campo messages.

6. Número real, nome de exibição e PIN

Na mesma tela API Setup, adicione o número da empresa. A Meta envia um código por SMS ou ligação, pede o nome de exibição (o nome que aparece no perfil) e um PIN de verificação em duas etapas. Anote o PIN: ele é pedido para mudar ou remover o número depois.

O nome de exibição passa por revisão seguindo as regras de nome de exibição. Nome genérico ou diferente da marca costuma voltar.

7. Forma de pagamento e verificação da empresa

Cadastre o cartão no Billing Hub. Pela página de preços da Meta, sem forma de pagamento as respostas param de ser entregues depois das 1.000 mensagens de serviço grátis do mês. Os valores por categoria estão no artigo sobre o preço da API oficial do WhatsApp.

Depois, peça a verificação da empresa no portfólio. Ela não é obrigatória para mandar a primeira mensagem, mas é um dos caminhos para sair do limite inicial de 250 pessoas por dia e chegar a 2.000, segundo a documentação de limites. Nesta etapa vale o que o Nick repetiu na live: documento físico (passaporte ou CNH física, nada de CNH digital) e cartão do CNPJ emitido no dia.

8. Templates

Fora da janela de 24 horas, só template. Cada template precisa de nome, idioma e categoria: marketing, utilidade ou autenticação. Pela documentação de templates, a revisão pode levar até 24 horas, e um template aprovado pode ser pausado se receber denúncia ou tiver leitura baixa.

Comece com dois ou três: uma saudação para retomar contato, uma confirmação (utilidade) e, se fizer sentido, uma oferta (marketing). Não tente passar oferta como utilidade. A Meta reclassifica, e na live o Nick lembrou que a cobrança segue a intenção da mensagem.

9. Conectar no Chatwoot

No Chatwoot, vá em Configurações > Caixas de entrada > Adicionar caixa > WhatsApp e escolha WhatsApp Cloud. Na configuração manual, ele pede:

1. o Phone Number ID (ID do número);
2. o WhatsApp Business Account ID (ID da conta), que é um número diferente do anterior;
3. o token permanente do passo 4.

Os dois IDs ficam na tela API Setup, embaixo do número selecionado. O Chatwoot confere acesso ao número, acesso aos templates, webhook e assinatura. Com os quatro verificados, os templates aprovados aparecem sozinhos na hora de responder. Para testar, mande uma mensagem de outro celular para o número da empresa e responda pelo Chatwoot.

Um número por caixa de entrada. Se a empresa tem três números, são três caixas.

Configuração manual ou cadastro incorporado

O caminho acima é o manual: você cria o app e configura tudo. Ele funciona no Chatwoot instalado no seu servidor, mas, pela comparação da documentação do Chatwoot, não tem coexistência.

O cadastro incorporado (Embedded Signup) é aquela janela da Meta que abre quando o cliente clica em conectar. Ele permite coexistência e não exige que o cliente mexa em token. Para oferecer isso no seu Chatwoot, o seu app precisa estar aprovado como Tech Provider. Faz sentido quando você vai conectar números de vários clientes, porque cada um só clica em conectar e você não repete o processo. Expliquei as etapas e o que a Meta confere em Tech Provider WhatsApp.

Para uma empresa com um ou dois números, o manual resolve.

Erros comuns que travam a API oficial

Os erros de identidade que reprovam a análise do app (Gmail, telefones diferentes em cada cadastro, site vazio) eu listei no artigo do Tech Provider. Aqui vão os que aparecem na configuração do dia a dia:

• Número que ainda está no WhatsApp. A Meta não registra número em uso. Apague a conta do WhatsApp nele ou use coexistência.
• Número banido. A documentação é clara: número banido só entra na API depois de desbanido pelo processo de análise.
• Número virtual ou sem sinal. Na live, o Nick contou que a Meta pode pedir o código por SMS, ligação ou WhatsApp, e você não escolhe. Sem receber, é dia perdido.
• Token temporário em produção. Funciona no teste e para de funcionar horas depois. Use o do usuário do sistema.
• Token sem whatsapp_business_management. No Chatwoot, as mensagens funcionam, mas os templates não sincronizam.
• Sem forma de pagamento. As respostas param no meio do mês, depois da cota grátis.
• "Conta não qualificada" na coexistência. Segundo o Nick, costuma ser falta de uso: o número precisa de alguns dias de conversa real antes de conectar.
• HTTPS quebrado. Certificado inválido derruba webhook e, no caso do Tech Provider, a análise.

Depois de configurar: primeiros cuidados

Mantenha o Chatwoot atualizado. Na semana da live, a Meta mudou algo no código sem avisar e o Chatwoot publicou a correção em menos de 24 horas. Quem estava numa versão antiga ficou sem receber mensagem.

Comece mandando template para quem já é cliente ou deu permissão. A regra de opt-in da Meta exige que a pessoa tenha aceitado receber mensagens da sua empresa, com o nome da empresa claro no pedido. Lista comprada derruba a qualidade do número rápido.

Se ainda está decidindo se a oficial faz sentido para a sua operação, os critérios estão em API oficial do WhatsApp vale a pena.

Perguntas frequentes

Como ter a API oficial do WhatsApp sem ser programador?

Pela configuração manual dá para fazer só clicando nas telas da Meta e colando os IDs no Chatwoot. O que exige conhecimento técnico é instalar e manter o Chatwoot no servidor.

Quanto tempo leva para configurar a API oficial do WhatsApp?

A parte técnica cabe em uma tarde. O que demora é o que depende da Meta: revisão do nome de exibição, dos templates (até 24 horas cada) e da verificação da empresa.

Posso usar o mesmo número no celular e na API oficial?

Pode, com coexistência, que é feita pelo cadastro incorporado de uma plataforma aprovada como Tech Provider. Na configuração manual, o número sai do app.

A API oficial do WhatsApp é paga?

Receber mensagem não é cobrado. A Meta cobra templates de marketing, utilidade e autenticação, e as respostas dentro da janela depois de 1.000 por mês por número.

Preciso ser Tech Provider para usar a API oficial?

Não. Para usar no seu próprio número, a configuração manual basta. O Tech Provider é para quem vai conectar números de clientes pelo botão de conectar.

Seu Chatwoot pronto para a API oficial

No AstraChat, o Chatwoot Pro da Astra Online, a caixa da API oficial já vem integrada ao disparador com templates, aos flows, ao Kanban e às ligações pelo WhatsApp. Roda no seu servidor, com a sua marca e sem cobrança por atendente.

Ele vem na Comunidade Astra Online, com código-fonte, atualizações, grupo VIP e a primeira instalação feita pelo especialista em Chatwoot Raphael Popiolek. Travou em algum dos nove passos? Me chame no WhatsApp com o print da tela e a mensagem de erro.