Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Começar

Como enviar a primeira mensagem pela API de WhatsApp?

Crie a instância, conecte o número, guarde a chave e envie a primeira mensagem de WhatsApp por cURL, Node, Python ou PHP, com limites e erros.

4 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Para enviar a primeira mensagem, crie a instância no painel, conecte o número por QR ou código, guarde a chave pbwa_… e chame POST /messages/text com o cabeçalho apikey. Leva poucos minutos. O limite padrão é de 10 mensagens por minuto e 500 por dia.

Este guia leva uma instância nova da API de WhatsApp da ProxyBox da criação até a primeira mensagem enviada. A API não é a oficial da Meta: o WhatsApp pode bloquear qualquer número, por isso use um número que você possa perder e leia a política de uso aceitável antes de começar.

Posso testar antes, sem número e sem pagar?

Pode. O sandbox é uma instância de teste grátis, já conectada, uma por conta, por 30 dias e com 100 envios por dia. Nada sai para o WhatsApp; as respostas vêm marcadas com "sandbox": true, e você simula mensagens recebidas para testar o seu receptor de avisos. Os passos 4 e 5 abaixo valem igual para o sandbox. Recurso em beta: pode mudar.

O que preciso antes de começar?

Você precisa de três coisas: o celular do número, com chip ativo e WhatsApp instalado; uma conta na ProxyBox com uma instância contratada; e, se for receber avisos, um endereço https do seu sistema.

  • O celular do número com o chip ativo e o WhatsApp instalado.
  • Uma conta na ProxyBox e uma instância contratada (a página API de WhatsApp mostra os planos).
  • Um endereço https do seu sistema, se for receber avisos (veja o guia do aviso automático).

1. Como crio a instância?

Pelo painel, em API de WhatsApp: dê um nome que você reconheça e a instância aparece como Preparando por alguns instantes.

No painel, abra API de WhatsApp e crie a instância com um nome que você reconheça, como "Atendimento da loja". Cada instância é um número, tem uma chave só dela e aparece como Preparando por alguns instantes.

Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.

Testar grátis

2. Como conecto o número?

Leia o QR do painel em Aparelhos conectados no WhatsApp do número, ou digite o código de pareamento. Pela API, o passo a passo está em conectar por QR, código e passkey.

Quando o estado mudar para Aguardando a leitura do QR:

  1. No celular do número, abra o WhatsApp e entre em Configurações > Aparelhos conectados.
  2. Toque em Conectar um aparelho e leia o QR que aparece no painel. Se a câmera não ler, escolha Conectar com número de telefone e digite o código de pareamento que o painel mostra.
  3. O estado muda para Conectado e o número aparece no painel.

O QR vale poucos segundos e se renova sozinho. Se o painel mostrar Desconectado, repita o passo.

3. Onde guardo a chave?

Em um cofre ou numa variável de ambiente do seu sistema. A chave aparece uma vez, na criação da instância, e abre só aquela instância.

A chave tem o formato pbwa_ seguido de 40 caracteres e aparece uma vez, quando a instância é criada. Guarde em um cofre ou em uma variável de ambiente do seu sistema. Se perder ou suspeitar de vazamento, use Gerar chave nova: a anterior para de funcionar na hora.

4. Como envio a primeira mensagem?

Com POST /messages/text, a chave no cabeçalho apikey e o destino com código do país e DDD, só dígitos. A base da API é https://proxybox.com.br/api/whatsapp/v1.

A base da API é https://proxybox.com.br/api/whatsapp/v1 e a chave vai no cabeçalho apikey. O número de destino vai com o código do país e o DDD, só com dígitos.

curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/text" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","text":"Olá! Teste da API de WhatsApp."}'
const resp = await fetch("https://proxybox.com.br/api/whatsapp/v1/messages/text", {
  method: "POST",
  headers: { apikey: process.env.WA_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ to: "5547999999999", text: "Olá! Teste da API de WhatsApp." }),
});
console.log(resp.status, await resp.json());

Python

Use requests (como abaixo). O agente padrão do urllib do Python pode receber 403 do Cloudflare; se usar urllib, defina um User-Agent próprio.

python
import os, requests

r = requests.post(
    "https://proxybox.com.br/api/whatsapp/v1/messages/text",
    headers={"apikey": os.environ["WA_KEY"]},
    json={"to": "5547999999999", "text": "Olá! Teste da API de WhatsApp."},
    timeout=30,
)
print(r.status_code, r.json())
PHP
<?php
$ch = curl_init('https://proxybox.com.br/api/whatsapp/v1/messages/text');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['apikey: ' . getenv('WA_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['to' => '5547999999999', 'text' => 'Olá! Teste da API de WhatsApp.']),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', curl_exec($ch);

O texto aceita de 1 a 4.096 caracteres, reply_to (id de uma mensagem para responder) e mentions (telefones a mencionar, ou "everyone" em grupo). O destino também pode ser um grupo, pelo id que termina em @g.us.

Resposta de sucesso:

json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-10T14:03:22-03:00" }

O painel também tem o botão Enviar mensagem de teste, que faz esta mesma chamada com a sua chave.

5. Como vejo o estado da instância?

Com GET /instance, que devolve o estado, o número, os limites e o uso do dia.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/instance" -H "apikey: SUA_CHAVE"

A resposta traz o estado (connected, disconnected, awaiting_qr...), o número, os limites e o uso do dia. Use esta rota antes de rotinas longas para saber se a instância está conectada. Para conferir se o WhatsApp responde de verdade, use GET /health: ele faz uma ida e volta real e informa se a instância está conectada mas sem resposta. [Recurso em beta: pode mudar.]

Quais são os limites e os erros mais comuns?

No padrão, cada instância envia até 10 mensagens por minuto e 500 por dia, com pausa de 3 a 10 segundos entre uma e outra; você pode deixar mais devagar, nunca mais rápido.

No padrão, cada instância envia até 10 mensagens por minuto e 500 por dia, com pausa de 3 a 10 segundos entre uma e outra. Você pode deixar mais devagar no painel, nunca mais rápido.

Código error O que fazer
401 invalid_key Conferir a chave; se trocou, atualizar o sistema
403 instance_paused A equipe pausou a instância; fale com o suporte
403 ip_not_allowed A chave tem IPs permitidos e este IP não está na lista
403 status_disabled O status vem desligado; ligue nos ajustes
202 (aprovação) A mensagem ficou pendente de aprovação humana; não é erro
409 not_connected Ler o QR de novo no painel
409 new_contacts_locked O WhatsApp restringiu contatos novos; esperar retry_after
422 invalid_request Corrigir os campos indicados em fields
422 number_not_on_whatsapp O telefone de destino não tem WhatsApp
429 rate_limited ou daily_limit Esperar retry_after segundos
501 unsupported O recurso não está disponível nesta instância
502 engine_unavailable Tentar de novo; nada foi enviado
503 instance_preparing Aguardar a instância ficar pronta

A tabela completa, com os erros de mídia, grupos e agendamento, está em erros e limites.

Que cuidados mantêm o número saudável?

Escrever só para quem espera receber, respeitar o ritmo e variar o texto. Nenhum cuidado garante que o WhatsApp não bloqueie o número.

  • Peça consentimento e deixe fácil sair da lista. Mensagem para quem não conhece você gera denúncia, e denúncia gera bloqueio.
  • Não repita o mesmo texto para muita gente. Varie e personalize.
  • Use Idempotency-Key nas chamadas de envio para não duplicar mensagem quando o seu sistema tentar de novo.
  • Respeite o 429. Esperar o retry_after é mais barato do que perder o número.
  • Trate o 409. Se a instância desconectou, pare as filas até conectar de novo.

Para entender o que o WhatsApp considera comportamento de risco, leia WhatsApp banido: causas na API e no Business.

Para onde vou depois da primeira mensagem?

Com a primeira mensagem enviada, escolha o próximo guia pelo que você precisa fazer. Em 12/11/2026 foram provados em aparelho real, pela API pública: texto, texto temporário (expires_in), texto citando (reply_to), imagem por base64, documento (PDF), voz e áudio como arquivo, figurinha, localização, contato, link (sai como texto com o endereço), enquete, botões de resposta e de ação (link, copiar código e ligar), reação (colocar e tirar), editar, apagar para todos, encaminhar, marcar como lida, ler conversa, não perturbe, aprovação humana, agendamento de uma mensagem, etiquetas, ajustes e proteções (IP permitido, status desligado), eventos por consulta e as rotas no estilo da Evolution (sendText, sendButtons, whatsappNumbers) e da Z-API (send-text). Não funcionam lista (menu) e carrossel. Ainda não foram provados: botão de localização, vídeo, status (stories), grupos além de listar, avisos de mensagens recebidas (voto de enquete, resposta de botão, reação, texto, foto e voz), recusa de chamada, S3, Chatwoot, bots e imagem por URL. Tudo da versão 1.2 que não está na lista de provados segue em beta: pode mudar.

  • Mandar arquivo: imagem, vídeo, áudio, voz, documento e figurinha.
  • Enquete, reação, editar e apagar: mensagens e ações.
  • Grupos e canais: criar e administrar.
  • Conferir um número antes de enviar: contatos.
  • Ler conversas e baixar o que o cliente mandou: conversas e mídia recebida.
  • Enviar numa hora marcada: agendar uma mensagem.
  • Todas as rotas num só lugar: referência.
  • Botões de resposta e de ação: botões (provados em 12/11/2026; lista e carrossel não funcionam).
  • Receber sem endereço público: receber por consulta.
  • Responder sozinho com um bot ou IA: bots e aprovação humana.
  • Atender em equipe: Chatwoot e equipe e papéis.
  • Proteger a chave: IPs permitidos e segurança.
  • Ligar a outras ferramentas: integrações, modelos prontos e nós do n8n.
  • Já usa a Evolution ou a Z-API: migrar da Evolution e migrar da Z-API.
  • Trabalha com um assistente de IA: Claude e Cursor.

Veja também

Índice completo: todos os guias.

Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026, contra o catálogo da versão 1.2 da API.

Perguntas frequentes

Preciso deixar o celular ligado?
O celular do número precisa estar com o chip ativo e, de tempos em tempos, conectado à internet. Se o WhatsApp desconectar o aparelho, a instância avisa e você lê o QR de novo.
Posso usar o mesmo número em duas instâncias?
Não. A regra é uma instância por número.
A chave aparece de novo?
Não. Ela aparece uma vez. Se perder, gere outra no painel; a anterior para de funcionar na hora.
Dá para enviar mensagem para quem nunca falou comigo?
Tecnicamente sim, mas é a principal causa de bloqueio de número. Escreva só para quem espera receber e respeite o ritmo.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp