API oficial do WhatsApp: o que é e como funciona (2026)

A API oficial do WhatsApp é a WhatsApp Cloud API, o serviço da própria Meta que permite a um sistema enviar e receber mensagens por um número do WhatsApp Business. É o único caminho autorizado para automatizar o WhatsApp, e por isso ele vem com regras: janela de 24 horas para mensagens livres, mensagens aprovadas pela Meta fora dela e um limite de envio que cresce com a qualidade do número. Qualquer empresa pode usar, sem contrato com a Meta, e desde 2025 dá para conectar o número sem tirá-lo do celular.

Este artigo explica o que a API é, o que ela permite, o que a Meta cobra, quem pode usar e como conectar um número em minutos.

O que é a API oficial do WhatsApp, em resposta curta

API é a sigla de interface de programação. Na prática, é uma porta pela qual um software fala com outro. A API oficial do WhatsApp é a porta que a Meta abre para que um sistema, seja um painel de atendimento, um CRM ou uma automação, use um número do WhatsApp Business por programação: enviar mensagem, receber o que o cliente escreveu, saber se foi entregue e lido.

O nome técnico atual é WhatsApp Cloud API, porque ela roda na nuvem da Meta. O nome comercial é WhatsApp Business Platform. Os dois se referem à mesma coisa. Quando alguém diz "API do WhatsApp Business", "Cloud API" ou "API oficial", está falando deste serviço.

Três coisas a API oficial não é:

• Não é um aplicativo. Não existe tela da Meta para operar a API. Quem dá a tela é um provedor, que conecta o número e oferece painel, envio e relatórios por cima da API.
• Não é um chatbot. A API entrega e recebe mensagens. O que responder, quem decide é o sistema conectado a ela.
• Não é a mesma coisa que uma ferramenta que "lê" o WhatsApp Web. Essa diferença é o assunto de API oficial x não oficial, e ela decide se o número continua existindo amanhã.

Por que a Meta criou a API e o que ela proíbe fora dela

O app WhatsApp Business foi feito para uma pessoa atender pelo celular. Quando o negócio cresce, aparecem necessidades que o app não cobre: um sistema que envie a confirmação do pedido sozinho, um lembrete de consulta para 300 pacientes, uma equipe respondendo o mesmo número de vários computadores, um registro de cada conversa dentro do CRM.

Antes da API oficial, a única forma de fazer isso era automatizar o WhatsApp por fora, com programas que simulam uma sessão do WhatsApp Web ou um celular. A Meta trata esse uso como violação. A WhatsApp Business Messaging Policy diz, em resumo, que quem usa um serviço que viola os termos, como enviar mensagens em massa não autorizadas, pode ter o acesso aos serviços do WhatsApp Business restringido ou removido. As diretrizes de mensagens vão na mesma linha e proíbem clientes não oficiais, envio em massa e automação que prejudique o WhatsApp ou seus usuários. A detecção é automática e é alimentada pelas denúncias de quem recebe.

A API oficial existe para dar um caminho legítimo a essas necessidades. A troca é simples: a empresa ganha automação, estabilidade e um número que não cai por "uso indevido"; em contrapartida, aceita as regras da Meta sobre quando pode escrever para alguém e o que pode enviar.

App WhatsApp Business x API: o que muda na prática

A última linha é a que mais confunde. Até 2025, usar a API significava tirar o número do celular. Hoje existe a coexistência, tratada mais abaixo, em que o número continua no app e passa a responder também pela API.

On-Premises acabou: a Cloud API é a única arquitetura oficial

Durante anos a Meta ofereceu duas formas de usar a API: a Cloud API, hospedada por ela, e a On-Premises API, em que a empresa ou o provedor rodava um servidor próprio do WhatsApp. Segundo o changelog da Meta, a On-Premises foi desligada em outubro de 2025. Desde então, toda integração oficial roda na Cloud API.

Para quem contrata, isso simplifica a decisão: todo provedor sério está em cima da mesma Cloud API, e a diferença entre eles está no que constroem por cima dela.

O que dá para fazer com a API

A API cobre três usos, e vale entender cada um porque as regras da Meta mudam de um para o outro.

Atendimento: janela de 24 horas e mensagens livres

Quando um cliente escreve para o número, a Meta abre uma janela de atendimento de 24 horas. Dentro dela a empresa pode responder o que quiser: texto, imagem, áudio, documento, botões. Cada nova mensagem do cliente reinicia a contagem.

Passadas 24 horas sem o cliente escrever, a janela fecha. A partir daí a empresa não consegue mandar mensagem livre; a Meta recusa com o erro 131047. Para reabrir a conversa é preciso usar uma mensagem aprovada pela Meta, o que a documentação chama de template. O detalhe de como a janela funciona, inclusive a janela de 72 horas de quem chega por anúncio, está em janela de 24 horas do WhatsApp.

Para quem atende, o painel precisa mostrar se a janela de cada conversa está aberta, senão o atendente descobre isso pelo erro. No Frame Conexa, a lista de conversas sinaliza a janela e troca o modo de envio sozinha quando ela fecha.

Envio em massa com mensagens aprovadas pela Meta

Fora da janela, a empresa só inicia conversa com um template. É uma mensagem com texto fixo e variáveis, enviada para aprovação da Meta antes do primeiro uso, em uma de três categorias: marketing, utilidade e autenticação. Promoção é marketing; confirmação de pedido e lembrete de consulta são utilidade; código de verificação é autenticação. Como escrever um template que passa está em template do WhatsApp aprovado.

O envio em massa oficial é isso: uma campanha de templates para uma lista de contatos que deram permissão. Duas regras da Meta valem aqui e não são do provedor. A primeira é o opt-in: só se pode escrever para quem deu o número e concordou em receber mensagens da empresa. A segunda é o limite de envio, que começa em 250 destinatários únicos por 24 horas e sobe com a qualidade. O artigo sobre disparo em massa no WhatsApp oficial trata dos dois em detalhe.

Integração: webhooks, API REST, automações e IA

A terceira frente é a integração com o resto do negócio, e ela usa dois mecanismos. A API REST é o lado do envio: o sistema faz uma requisição HTTP e a mensagem sai. O webhook é o lado do recebimento: a Meta chama uma URL da empresa cada vez que chega mensagem ou muda o status de uma enviada, e assina cada chamada com o cabeçalho X-Hub-Signature-256 para que o receptor confira a origem.

Um provedor coloca uma camada por cima disso. No Frame Conexa, o envio é uma chamada à API pública, autenticada por um token criado no painel:

curl -X POST https://frameconexa.com/api/v1/instances/$FRAME_CONEXA_INSTANCE_ID/messages \
  -H "Authorization: Bearer fc_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"5585999990000","type":"text","text":{"body":"Olá!"}}'

E o recebimento chega em um envelope próprio, com o payload exatamente como a Meta o mandou, assinado com X-Frame-Signature-256:

{
  "type": "messages",
  "clientId": "8",
  "instanceId": "6ed76b84-4d65-4f3d-88c1-8d4174bdce73",
  "customerId": null,
  "customerRef": null,
  "payload": {}
}

É o mesmo mecanismo que alimenta n8n, Make e agentes de IA. O guia completo, com validação de assinatura e tratamento de duplicatas, está em como integrar a Cloud API por webhook e na documentação.

Quanto custa: o que a Meta cobra e o que o provedor cobra

A conta tem duas partes, e elas vão para lugares diferentes.

A Meta cobra pelo uso da API. Quem paga é a empresa dona do número, com um cartão cadastrado na própria conta do WhatsApp Business dentro do Business Manager. A fatura é da Meta, não do provedor.

O provedor cobra pelo software. É o painel, a conexão, as campanhas, os relatórios, a API pública. Alguns provedores cobram também um adicional por mensagem, em cima da tarifa da Meta. O Frame Conexa não: a assinatura é por número, e a mensagem custa o que a Meta cobra, sem intermediário. Os planos estão em preços por número.

Preço por mensagem entregue, por categoria

Desde 1º de julho de 2025 a Meta cobra por mensagem de template entregue. O modelo anterior, que cobrava por conversa de 24 horas, foi descontinuado. Só as três categorias de template são cobradas, e a tarifa depende da categoria e do país do número de quem recebe, não do país da empresa.

Para o Brasil, a tabela publicada pela Meta em setembro de 2026 traz marketing na casa de 6 centavos de dólar por mensagem e utilidade e autenticação em 0,68 centavo de dólar, valor que a própria Meta usa como exemplo na página sobre as mudanças de outubro. Confira o rate card oficial antes de fechar qualquer conta: a Meta atualiza a tabela e o valor em reais depende da moeda de faturamento da conta. Há desconto por volume só para utilidade e autenticação, contado no portfólio inteiro e zerado todo mês; marketing não tem desconto por volume.

A tabela completa, com o que muda em reais e como estimar o custo de uma campanha, está em WhatsApp Business API: preço.

Mudança de 01/10/2026: mensagens de serviço passam a ser cobradas

Esta é a mudança que mais afeta quem usa a API para atender. Hoje a resposta livre dentro da janela de 24 horas é gratuita. Segundo a página oficial de atualizações de preço, a partir de 1º de outubro de 2026 a Meta passa a cobrar por mensagem tanto a mensagem de serviço, que é a resposta livre dentro da janela, quanto o template de utilidade enviado dentro da janela. A tarifa segue a tabela de utilidade e autenticação do país do destinatário.

O que não muda: receber continua gratuito, e a janela de 72 horas aberta por anúncio Click-to-WhatsApp continua isentando a entrega. O app WhatsApp Business no celular também não é afetado; a cobrança é da plataforma.

Atenção: vários provedores repetem que haverá uma franquia mensal de mensagens de serviço gratuitas por número antes da cobrança. A página oficial da Meta não menciona franquia nenhuma. Trate essa informação como não confirmada até o rate card de outubro sair.

Quem pode usar: é só para empresa grande?

Não. A API oficial nasceu restrita a grandes marcas, que precisavam de contrato com um parceiro e de aprovação da Meta. Com a Cloud API e o Embedded Signup, qualquer empresa com um número e uma conta no Business Manager pode conectar, e o processo cabe em uma tela.

O que a Meta exige de fato:

• Um número de telefone que receba SMS ou ligação para verificação, ou um número já em uso no app WhatsApp Business, no caso da coexistência.
• Uma conta no Meta Business Manager, gratuita, que passa a ser o portfólio dono do número.
• Um cartão cadastrado nessa conta para pagar as mensagens à Meta. Sem ele, o número conecta e responde dentro da janela, mas não dispara template.
• Respeito à política de mensagens, em especial o opt-in.

A verificação da empresa, com documentos, é opcional para começar. Ela só entra quando o negócio quer subir o limite de envio além do degrau inicial, e é o assunto de limite de mensagens na WhatsApp Business API.

Vale conhecer também os dois tipos de provedor que a Meta reconhece, porque isso muda quem manda a fatura. O Solution Partner é o parceiro que fatura o cliente diretamente e pode estender linha de crédito; no onboarding com ele, a empresa não cadastra cartão. O Tech Provider oferece o software e não tem linha de crédito: a empresa cadastra o pagamento na própria conta e paga a Meta direto, sem acréscimo por mensagem. O Frame Conexa é um Tech Provider verificado pela Meta, e por isso não consegue cadastrar o cartão pelo cliente. É um limite do programa, e o produto lida com ele entregando o link do Business Manager quando a conta ainda não tem pagamento.

Coexistência: usar a API sem tirar o número do celular

Até 2025, conectar um número à API exigia removê-lo do app. O negócio perdia o histórico no aparelho e a equipe perdia o jeito de atender que já conhecia. Muita empresa pequena desistia ali.

A coexistência resolve isso. O número continua no app do celular e passa a existir também na Cloud API. Quem atende pelo app continua atendendo; o sistema conectado à API vê as mesmas conversas, envia campanhas e recebe cada mensagem por webhook. Se o dono do número autorizar, a Meta envia ao provedor o histórico dos últimos 180 dias, em levas, e o painel já nasce com as conversas antigas.

As regras oficiais da coexistência que importam para quem decide:

• O app precisa estar na versão 2.24.17 ou superior.
• O envio pela API fica fixo em 20 mensagens por segundo nesse número.
• Alguns recursos do app são desativados: grupos, listas de transmissão, mensagens temporárias e visualização única. Chamadas e catálogo aparecem como não suportados.
• O celular precisa continuar ativo. Um aparelho principal inativo por cerca de 14 dias desconecta a integração.

É o modo padrão do Frame Conexa e o caminho recomendado para quem já atende pelo app. O detalhe de cada limitação, e como migrar sem perder o número, está em coexistência do WhatsApp Business com a API.

Nota: para um número novo, sem app no celular, existe o outro modo: o número vive só na Cloud API, sem o limite de 20 mensagens por segundo e sem as restrições de recurso do app. A escolha é feita no primeiro passo da conexão.

Como conectar em minutos com o Embedded Signup

O Embedded Signup é a janela da própria Meta que aparece dentro do site do provedor. Nela, a empresa entra com o login do Facebook, escolhe ou cria o portfólio no Business Manager e a conta do WhatsApp Business, indica o número e autoriza o provedor a operá-lo. Ao final, a Meta devolve os identificadores do número e um código trocável por um token de acesso, sem o qual o provedor não envia nem recebe nada.

O que acontece do lado do Frame Conexa depois do clique:

1. O painel abre o Embedded Signup no modo escolhido, coexistência ou número novo.
2. A empresa autoriza na janela da Meta. Em coexistência, o app do celular pede a confirmação e, se autorizado, o compartilhamento do histórico.
3. O servidor troca o código pelo token, confere o estado do número, assina os webhooks da conta e grava a instância. O token fica cifrado; nunca aparece no painel.
4. Em coexistência, as sincronizações de histórico e contatos começam. Em número novo, o servidor registra o número na plataforma.

Quem opera o Embedded Signup precisa ser um Solution Partner ou um Tech Provider aprovado pela Meta, com App Review concluído. É isso que está "do outro lado da janela", e é o assunto de Embedded Signup do WhatsApp. Para quem contrata a vaga mas não é quem tem o celular, o Frame Conexa gera um link de conexão: o cliente final abre, faz só o Embedded Signup e o número nasce na conta de quem contratou.

Limites que a Meta impõe: capacidade, qualidade e opt-in

Todo limite que aparece no dia a dia da API é da Meta. Vale repetir porque a suspeita natural de quem paga é que o limite seja do provedor.

Capacidade do número. É a quantidade de destinatários únicos para quem a empresa pode iniciar conversa fora da janela, numa janela móvel de 24 horas. Os degraus oficiais são 250, 2.000, 10.000, 100.000 e ilimitado. Desde outubro de 2025 o limite é calculado no portfólio e compartilhado por todos os números dele. Para sair do primeiro degrau, a empresa verifica o negócio no Business Manager ou entrega 2.000 mensagens fora de janela para 2.000 números únicos em 30 dias com boa qualidade. A escalada seguinte é automática: qualidade alta em todos os números e uso de ao menos metade do limite atual nos últimos 7 dias sobem um degrau em até 6 horas.

Qualidade. Cada número tem uma classificação, verde, amarela ou vermelha, calculada pelo retorno dos usuários nos últimos 7 dias: bloqueios, denúncias e motivos informados. Uma versão antiga da regra dizia que a qualidade vermelha derrubava o limite um degrau em 7 dias. Segundo a página oficial sobre as mudanças de limites, isso deixou de valer em outubro de 2025: o limite não é mais rebaixado por queda de qualidade. A qualidade continua contando para subir de degrau, para as restrições de spam e para a pausa de templates, que a Meta pausa sozinha quando ficam com qualidade baixa.

Limite por pessoa. A Meta também limita quantos templates de marketing um mesmo usuário recebe, somando todas as empresas que falam com ele. Quando bate, a API devolve o código 131049 e a orientação é esperar 24 horas. Não é um limite do seu número, e insistir prolonga o bloqueio.

Opt-in. Só se escreve para quem deu o número e concordou em receber. Quem pede para parar tem de ser atendido, inclusive quando pede fora do WhatsApp. O erro 131050 é a Meta avisando que a pessoa desativou o marketing da sua empresa, e o contato precisa sair da lista.

Um provedor não elimina esses limites, porque não pode. O que ele faz é torná-los visíveis antes do erro: mostrar a capacidade do número antes de criar a campanha, pausar o envio quando a Meta sinaliza spam, tirar da lista quem pediu para sair e traduzir cada código em ação, como em erros da API do WhatsApp.

Próximo passo

Se o número já atende pelo app, o caminho mais curto é conectá-lo em coexistência e ver as conversas no painel no mesmo dia. Os planos por número mostram o que cada tipo de número faz; para quem vai integrar, o guia de primeira mensagem leva do token ao primeiro envio.