Pular para o conteúdo
apiwpp

API de WhatsApp: o que é, como funciona e quando usar

O que é uma API de WhatsApp, os dois caminhos (Cloud API oficial e WhatsApp Web), como enviar e receber mensagens por HTTP e quando vale a pena usar.

Equipe apiwpp · 12 min de leitura

O seu sistema já sabe quando um pedido foi pago, quando uma consulta é amanhã e quando um boleto vence. O cliente, por outro lado, lê o WhatsApp muito antes de abrir o e-mail. Enquanto alguém da equipe copia e cola essas mensagens à mão, o aviso sai atrasado, sai errado ou simplesmente não sai.

Uma API de WhatsApp resolve exatamente essa distância: ela deixa o seu código enviar e receber mensagens do WhatsApp com chamadas HTTP, do mesmo jeito que ele já conversa com o gateway de pagamento ou com o serviço de e-mail. Nada de celular na mesa nem de extensão no navegador.

Este guia explica o que é uma API de WhatsApp, os dois caminhos que existem para usar uma, como o fluxo funciona na prática na apiwpp (conectar o número, enviar pela fila, receber por webhook) e em quais situações ela faz sentido. No fim, você tem os primeiros passos e os tutoriais por linguagem.

O que é uma API de WhatsApp

Uma API (interface de programação) é um contrato entre dois sistemas: um lado faz uma requisição num formato combinado, o outro responde num formato combinado. Uma API de WhatsApp é esse contrato aplicado ao WhatsApp. Na prática, ela oferece duas coisas:

  • Enviar: o seu sistema faz uma requisição HTTP (por exemplo, um POST com o número do destinatário e o texto) e a API entrega a mensagem pelo WhatsApp de um número seu.
  • Receber: quando alguém responde, ou quando o status de uma mensagem muda (enviada, entregue, lida), a API avisa o seu sistema com uma requisição HTTP para um endereço que você informou. Esse aviso se chama webhook.

Com esses dois lados, o WhatsApp deixa de ser um aplicativo que alguém opera e vira um canal que o seu software usa: o sistema de pedidos confirma a compra, a agenda lembra a consulta, o CRM registra a resposta do cliente na ficha dele.

Uma API de WhatsApp não é um aplicativo de atendimento nem uma caixa de entrada compartilhada. Ela é a peça de integração. Se você quer uma tela com vários atendentes, essa tela é o seu sistema (ou um produto que você já usa), e a API é o que liga essa tela ao WhatsApp.

Os dois caminhos: Cloud API oficial e protocolo do WhatsApp Web

Existem dois jeitos de colocar o WhatsApp dentro de um sistema, e eles são bem diferentes.

A API oficial, a WhatsApp Cloud API, é oferecida pela Meta: o número é registrado numa conta comercial, as mensagens que a empresa inicia usam modelos aprovados pela Meta e a cobrança é por mensagem, conforme a categoria e o país (a tabela oficial de preços da Meta traz os valores).

A API não oficial conecta um número comum pelo protocolo do WhatsApp Web, como um aparelho conectado: você escaneia um QR code e o serviço passa a enviar e receber em nome daquele número, sem aprovação de conta nem de mensagens.

A apiwpp segue o segundo caminho. Ela é uma API não oficial, não tem vínculo com o WhatsApp nem com a Meta, e o número continua sujeito às regras antispam do WhatsApp como qualquer usuário. A comparação completa, critério a critério, está no guia API oficial ou não oficial do WhatsApp.

Cloud API (oficial)Protocolo do WhatsApp Web (apiwpp)
Como o número entraRegistrado na plataforma da MetaAparelho conectado, por QR code ou código de 8 caracteres
AprovaçãoConta comercial e modelos de mensagem aprovadosNenhuma
CobrançaPela Meta, por mensagemPor número conectado, por mês
Selo de conta verificadaPossível, conforme a MetaNão existe
Risco de restriçãoBaixo, dentro das políticas da MetaExiste; a fila de envio reduz, sem eliminar
Os dois caminhos até o WhatsApp: a Cloud API da Meta, com conta comercial e modelos aprovados, e o protocolo do WhatsApp Web, com o número conectado como aparelho.

Como uma API de WhatsApp funciona na apiwpp

O fluxo tem três partes: conectar o número, enviar pela fila e receber por webhook. Antes delas, uma palavra sobre organização: a sua conta pertence a uma organização, cada sistema seu é um projeto (com as próprias chaves de API e o próprio endereço de webhook) e cada número de WhatsApp dentro de um projeto é uma conexão.

1. Conectar o número

Você cria uma conexão pela API e pede o QR code. O dono do número abre WhatsApp › Aparelhos conectados › Conectar um aparelho no celular e escaneia. Quem não pode escanear digita um código de pareamento de 8 caracteres.

curl -s https://api.apiwpp.com/connections/$ID/qr \
  -H "Authorization: Bearer $APIWPP_KEY"
{ "qr": "2@k8Jd0Qf3mX1pT7vZ9sLr4eYw6nHc2bGa,…", "status": "connecting" }

Quando o status passa a open, o número está pronto. A sessão fica salva e criptografada nos servidores: reinícios e atualizações não pedem um QR code novo, e o celular pode ficar desligado. O passo a passo, com a tela de pareamento e o código de 8 caracteres, está no tutorial como conectar um número por QR code e na página de conexão por QR code ou código de pareamento.

2. Enviar pela fila

O envio é um único POST /connections/{id}/send, com o destinatário só em dígitos (país, DDD e número), o texto e um clientRef, o seu identificador daquele envio:

curl -s -X POST https://api.apiwpp.com/connections/$ID/send \
  -H "Authorization: Bearer $APIWPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511988887777","message":"Olá, Ana! Sua consulta está confirmada para amanhã às 10h.","clientRef":"consulta-987-confirmacao"}'

A resposta chega na hora, com o status 202:

{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }

202 quer dizer "aceito, na fila": a mensagem ainda não saiu. Cada número tem uma fila que envia num ritmo parecido com o de uma pessoa. Por padrão, são no máximo 3 mensagens por minuto, 60 por hora e 200 por dia, com um intervalo aleatório de 3 a 8 segundos entre dois envios e pelo menos 30 segundos entre duas mensagens para a mesma pessoa. Destinatários novos, que nunca falaram com o número, têm um teto de 100 a cada 24 horas, e nos primeiros 14 dias depois de conectar os limites começam menores e sobem por etapas. A página da fila com ritmo anti-bloqueio detalha cada regra.

Além de texto, o mesmo endpoint envia imagem, vídeo, áudio, documento e figurinha a partir de uma URL https pública, localização e templates (mensagens salvas com variáveis como {{nome}}, sem aprovação da Meta). Antes de cada texto, o contato vê "digitando…" por um instante. E, antes de enviar, a apiwpp pergunta ao WhatsApp em qual endereço o número está registrado, para que contas antigas, criadas sem o nono dígito, recebam a mensagem.

O clientRef protege contra duplicidade: se a requisição der timeout e o seu sistema repetir o envio com o mesmo clientRef, a resposta é 200 com o job original e "duplicate": true, e nada entra na fila de novo.

3. Receber por webhook

Para cada evento, a apiwpp faz um POST no endereço de webhook do projeto. Uma resposta do cliente chega assim:

{
  "type": "message.incoming",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "clinica-12",
  "timestamp": "2026-06-01T12:00:00.000Z",
  "data": {
    "jid": "[email protected]",
    "phone": "+5511988887777",
    "body": "Confirmado, até amanhã!",
    "timestamp": 1780315200
  }
}

Os eventos mais usados são estes:

EventoQuando chega
message.incomingAlguém mandou uma mensagem para o número (texto, mídia ou localização)
message.deliveryO status de um envio mudou: sent, delivered, read ou failed
message.send_failedUm envio aceito com clientRef não vai acontecer, com o motivo
connection.statusO número conectou, caiu ou precisa de atenção
message.reactionAlguém reagiu a uma mensagem

Cada entrega é assinada com HMAC-SHA256, para o seu servidor conferir que o evento veio mesmo da apiwpp. A entrega é "pelo menos uma vez": se o seu endpoint falhar, há novas tentativas (6 no total, com intervalos crescentes), e o painel guarda o registro de cada entrega com a opção de reenviar. Por isso o seu código deve responder 2xx rápido e processar cada evento de forma idempotente. O tutorial de webhooks do WhatsApp mostra a verificação da assinatura em Node.js e PHP.

O fluxo completo: o número conectado como aparelho, o envio que entra na fila e responde 202, e os eventos que voltam para o seu sistema por webhook.

Quando usar uma API de WhatsApp

A regra prática: use uma API quando a mensagem nasce de um evento do seu sistema, ou quando a resposta do cliente precisa voltar para ele. Estes são os casos mais comuns.

Notificações que o cliente espera

Confirmação de pedido, pagamento aprovado, pedido enviado, código de rastreio, aviso de vencimento. São mensagens curtas, para quem já é cliente e está esperando por elas. O clientRef com o identificador do pedido garante que a mesma confirmação nunca sai duas vezes. O guia de notificações de pedido para e-commerce mostra o fluxo completo.

Lembretes de agendamento

Clínicas, salões e barbearias perdem horários porque o cliente esquece. Um lembrete na véspera, com a resposta do cliente voltando por message.incoming e atualizando a agenda, resolve boa parte disso. Veja os lembretes de agendamento com confirmação.

WhatsApp dentro de um SaaS ou CRM

Se você tem um produto, os seus clientes podem conectar o próprio número dentro dele: o seu sistema mostra o QR code, recebe as conversas por webhook e exibe tudo na tela do CRM. O guia sobre colocar o WhatsApp dentro do seu SaaS cobre a arquitetura, e agências que cuidam de vários clientes têm um guia próprio sobre gerenciar dezenas de números.

Atendimento integrado ao seu sistema

As mensagens recebidas abrem ou atualizam um chamado no seu sistema, e a equipe responde por ele, com texto, mídia e reações. No plano PRO, a API também marca mensagens como lidas e mostra presença ("digitando…", "gravando áudio").

Quando não usar

Uma API de WhatsApp não é ferramenta de disparo para listas frias ou compradas. Mensagem para quem nunca falou com você gera denúncias, e denúncias levam à restrição do número. Na apiwpp, a fila e o teto de destinatários novos existem justamente para impedir esse uso. Se o seu caso é campanha de marketing em grande volume ou exige o selo de conta verificada, a Cloud API oficial é a escolha certa. E, pelo mesmo motivo de a fila não garantir o horário exato de cada envio, não use a API para códigos de verificação ou avisos de emergência. O guia como evitar o bloqueio do número traz as boas práticas de envio.

Quanto custa

Na apiwpp, a cobrança é por número conectado, por mês, nos planos LITE e PRO, com mensagens ilimitadas dentro dos limites da fila: não há tarifa por mensagem. Adicionar um número no meio do mês é cobrado de forma proporcional, tudo vem numa fatura só por organização e o pagamento é por PIX, boleto ou cartão. O plano PRO acrescenta editar e apagar mensagens enviadas, marcar como lidas, presença e o IP dedicado como adicional. Os valores atuais e uma calculadora por quantidade de números estão em preços, e o guia quanto custa uma API de WhatsApp compara os modelos de cobrança do mercado.

Como começar hoje

  1. Liste as mensagens que o seu sistema deveria mandar e quem as recebe. Se todas vão para quem já é cliente e espera o aviso, uma API não oficial serve bem; se o plano é campanha em massa, avalie a Cloud API.
  2. Crie uma chave de API no painel com os escopos de que você precisa: connections:write para ver o QR code e messages:send para enviar. Guarde a chave num cofre de segredos, nunca no código.
  3. Conecte um número que já conversa com os seus clientes. Números com histórico começam em vantagem, e os primeiros 14 dias têm limites menores.
  4. Envie a primeira mensagem no tutorial da sua linguagem: Node.js, PHP e Laravel ou Python. Quem usa automação sem código tem o guia do n8n, com o nó HTTP Request e o nó Webhook.
  5. Configure o webhook e trate message.incoming e message.delivery. As páginas de integração para Node.js, PHP e Python trazem exemplos curtos de envio e recebimento, e a referência completa, em português, está na documentação.
  6. Teste com o seu número: crie sua conta e use os 7 dias de teste, sem cartão.

Perguntas frequentes

O que é uma API de WhatsApp?

É uma interface que deixa o seu sistema enviar e receber mensagens do WhatsApp por requisições HTTP. O seu código chama a API para enviar, e a API avisa o seu sistema por webhook quando chega uma mensagem ou quando o status de um envio muda. Assim, pedidos, agendas e CRMs conversam com os clientes sem ninguém copiar e colar mensagens.

Qual a diferença entre a API oficial e uma API não oficial?

A API oficial, a Cloud API da Meta, exige conta comercial, usa modelos de mensagem aprovados e cobra por mensagem. Uma API não oficial, como a apiwpp, conecta um número comum pelo protocolo do WhatsApp Web, como aparelho conectado, sem aprovação e com preço por número. A oficial oferece o selo verificado e volume alto; a não oficial é mais simples de começar, mas o número segue sujeito às regras antispam do WhatsApp.

Preciso de um número novo para usar a API?

Não. Você pode conectar o número que já usa, escaneando o QR code em Aparelhos conectados, como faria com o WhatsApp Web. Um número que já conversa com os seus clientes costuma ser a melhor escolha, porque quem recebe as mensagens já conhece o contato.

O celular precisa ficar ligado?

Não. O número funciona como um aparelho conectado, e a sessão fica salva e criptografada nos servidores da apiwpp. Reinícios e atualizações não pedem um QR code novo. Só um logout, feito pela API ou pelo celular, encerra a sessão.

A API de WhatsApp pode fazer o meu número ser bloqueado?

Pode, se for usada para enviar mensagens em massa a quem não pediu. O WhatsApp restringe números com comportamento de robô ou muitas denúncias. A fila da apiwpp reduz esse risco com limites de ritmo, teto de destinatários novos e aquecimento de 14 dias, mas nenhuma API não oficial pode garantir que um número nunca será restringido.

Preciso saber programar para usar uma API de WhatsApp?

Para integrar ao seu sistema, sim: são chamadas HTTP simples, com exemplos em Node.js, PHP e Python na documentação. Sem programar, ferramentas de automação como o n8n usam a API com um nó de requisição HTTP para enviar e um nó de webhook para receber.


Leia também:

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.