Provado em aparelho real em 10/11/2026: localização, contato, enquete, "digitando…", reação (e remover), editar, marcar como lida, encaminhar e apagar para todos. Beta: pode mudar: link, apagar só na instância, marcar áudio como ouvido, estrela e presença.
Atualização de 12/11/2026 (provado em aparelho real): texto citando (
reply_to), texto temporário, link (sai como texto com o endereço), enquete, reação (colocar e tirar), editar, apagar para todos, encaminhar e marcar como lida foram provados pela API pública. O status (stories) segue sem prova.
Além de texto e mídia, uma conversa de WhatsApp tem reações, respostas, edições e enquetes. Aqui estão as rotas para cada uma. Todas usam a base https://proxybox.com.br/api/whatsapp/v1, o cabeçalho apikey e o mesmo formato de erro dos primeiros passos. Para a lista completa de erros, veja erros e limites.
Como respondo, menciono e encaminho?
Com reply_to (o id da mensagem), mentions (telefones, ou "everyone" em grupo) e POST /messages/forward.
Quase todo envio aceita reply_to (o id de uma mensagem) para responder a ela, e o texto, a imagem, o vídeo e o documento aceitam mentions (lista de telefones, ou "everyone" em grupo).
{ "to": "5547999999999", "text": "Pode confirmar o endereço?", "reply_to": "3EB0B430B6F8F1D0E053AC120E0A9E5C" }
POST /messages/forward encaminha uma mensagem que a instância guardou: mande to (o destino) e id (a mensagem). O campo link_preview do texto existe por compatibilidade, mas é só informativo e não muda o que o WhatsApp mostra.
Como envio localização, contato e link?
Com POST /messages/location, /contact e /link. Na localização, só as coordenadas são enviadas.
| Rota | Campos | Observação |
|---|---|---|
POST /messages/location |
to, latitude, longitude, name, address |
Só as coordenadas são enviadas. name e address não chegam ao destinatário |
POST /messages/contact |
to, name (nome no cartão), phone (telefone do contato enviado) |
Manda um cartão de contato |
POST /messages/link |
to, url (https), caption |
Sai como texto com o endereço, sem prévia do site (a API não acessa a internet para montá-la) |
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/location" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"to":"5547999999999","latitude":-26.9194,"longitude":-49.0661}'
Como envio uma enquete?
Com POST /messages/poll, uma pergunta de até 255 caracteres e de 2 a 12 opções.
POST /messages/poll precisa de to, question (até 255 caracteres) e options (de 2 a 12 opções, até 100 caracteres cada). O campo max_answers diz quantas opções cada pessoa pode marcar: de 1 até o número de opções, e o padrão é 1.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/poll" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"to":"[email protected]","question":"Qual horário prefere?","options":["Manhã","Tarde","Noite"],"max_answers":1}'
Os votos chegam pelo aviso automático como atualização da mensagem da enquete.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisComo reajo, edito e apago uma mensagem?
Com as rotas POST /messages/{id}/reaction, /edit e /revoke, e DELETE /messages/{id}. Editar só funciona nos primeiros 15 minutos.
Estas rotas agem sobre uma mensagem que já existe. O id vai na rota, e o chat (o telefone ou o grupo da conversa) vai no corpo.
| Rota | Corpo | O que faz |
|---|---|---|
POST /messages/{id}/reaction |
chat, emoji |
Reage com o emoji. Emoji vazio remove a reação |
POST /messages/{id}/edit |
chat, text |
Troca o texto. Só até 15 minutos depois do envio |
POST /messages/{id}/revoke |
chat |
Apaga para todos |
DELETE /messages/{id}?chat=… |
Apaga só no histórico da instância | |
POST /messages/{id}/read |
chat |
Marca como lida (os dois risquinhos azuis) |
POST /messages/{id}/played |
chat |
Marca um áudio ou voz como ouvido |
POST /messages/{id}/star e /unstar |
chat |
Põe ou tira a estrela. Instável: às vezes pede para repetir a chamada |
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/3EB0B430B6F8F1D0E053AC120E0A9E5C/reaction" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"chat":"5547999999999","emoji":"👍"}'
Essas ações são "leves" e têm teto de 60 por minuto por instância. Apagar para todos também depende do WhatsApp: ele limita o tempo em que isso é possível.
Como mostro "digitando…" e a presença?
Com POST /typing (composing ou paused) e POST /presence (available ou unavailable).
POST /typingcomtoestateigual acomposing(começa a mostrar "digitando…") oupaused(para).POST /presencecomstateigual aavailable(aparece online) ouunavailable.
Um uso comum é mostrar "digitando…" por um ou dois segundos antes de uma resposta automática, para a conversa não parecer um corte seco. Isso é só conforto de leitura: não torna o número mais seguro.
Como a API mostra "digitando…" sozinha antes do texto?
Ligue o ajuste humanize da instância (em Ajustes, no painel, ou com PUT /instance/settings) e, antes de cada texto, a API mostra "digitando…" por alguns segundos e só então envia. O tempo cresce com o tamanho da mensagem, varia um pouco de uma vez para outra e nunca passa de 8 segundos.
- Por envio:
POST /messages/textaceita"humanize": trueoufalse, e esse campo vale mais que o ajuste da instância. - Instâncias novas já vêm com o ajuste ligado. As que já existiam ficam como estão (desligado) até você ligar.
- Se o "digitando…" falhar, a mensagem sai do mesmo jeito. O envio nunca fica preso por causa dele.
- Pausa e limites: a pausa entre mensagens e os limites por minuto e por dia continuam os mesmos, e a mensagem conta neles como sempre. A resposta da API não muda.
- Evolution e Z-API: funciona também nas rotas compatíveis. Se você já pede
delay(Evolution) oudelayTyping(Z-API), vale o que você pediu e não somamos outro "digitando…". - Só texto. Imagem, áudio e documento não mostram "digitando…" automático.
É conforto de leitura para quem recebe, não proteção: não torna o número mais seguro e não impede bloqueio.
Como recuso uma chamada?
Com POST /calls/reject, ou ligando a recusa automática.
POST /calls/reject com from (quem ligou) e call_id (que vem no aviso call.received) recusa a chamada de voz ou vídeo. A API não atende chamada.
Qual é um exemplo em Node.js?
Enviar um texto e reagir a ele em seguida, com o id que a resposta devolve.
const base = "https://proxybox.com.br/api/whatsapp/v1";
const h = { apikey: process.env.WA_KEY, "Content-Type": "application/json" };
const enviada = await (await fetch(`${base}/messages/text`, {
method: "POST", headers: h,
body: JSON.stringify({ to: "5547999999999", text: "Pedido confirmado." }),
})).json();
await fetch(`${base}/messages/${enviada.id}/reaction`, {
method: "POST", headers: h,
body: JSON.stringify({ chat: "5547999999999", emoji: "✅" }),
});
O que não existe na API?
Lista de transmissão e envio para todos os contatos não fazem parte da API. Os botões têm guia próprio (lista e carrossel não funcionam hoje), e o status está na seção acima. Mensagem em massa é proibida pela política de uso aceitável.
Como posto um status (stories)?
Resposta curta: o status (os "stories" do WhatsApp) é publicado com POST /status/text, /status/image ou /status/video, mas vem desligado. Para ligar, faça PUT /instance/settings com status_enabled: true. Enquanto estiver desligado, a API responde 403 status_disabled. O limite é de 3 por dia por instância, e o status vai para todos os contatos que têm o número da instância.
Recurso em beta: pode mudar. Não existe promessa de que o status apareça, nem de quanto tempo ele fica visível.
Por que o status vem desligado?
Porque ele é o único recurso da API que fala com muita gente de uma vez. Uma mensagem comum vai para uma pessoa; o status vai para a lista inteira de contatos do número, inclusive para quem nunca conversou com a sua empresa. Isso aproxima o recurso do que o WhatsApp mais observa: conteúdo repetido para muitos destinatários. A ProxyBox trata o status como a mensagem em massa que ele é e, por isso, exige uma decisão consciente do dono da instância e coloca um teto baixo.
Antes de ligar, pense em três coisas:
- O número tem uma lista de contatos que você quer mesmo alcançar? Em um número novo, o status quase não chega a ninguém.
- O conteúdo é de interesse de quem recebe? Promoção repetida todo dia é motivo de silenciamento e de denúncia.
- O número pode ser perdido? O risco de restrição do WhatsApp existe em qualquer recurso e é maior quando muita gente reage mal.
Como ligo o status?
Pela API (a mesma chave da instância) ou pelo painel, na área de ajustes, onde aparece o aviso "o status vai para todos os contatos que têm este número".
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/instance/settings" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"status_enabled": true}'
Para desligar, envie false. O ajuste vale só para essa instância.
Como publico um status de texto?
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/status/text" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"text": "Atendimento até as 18h hoje.", "allow_reshare": false}'
O texto tem de 1 a 700 caracteres. allow_reshare diz se os contatos podem repostar o status.
Resposta de sucesso, no mesmo formato dos outros envios:
{ "ok": true, "id": "3EB0A9F2C1D4B6E7F801", "status": "sent", "sent_at": "2026-11-12T09:30:00-03:00" }
Como publico imagem ou vídeo?
Com POST /status/image ou POST /status/video, passando a mídia em media (por url https ou base64) e, se quiser, uma caption.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/status/image" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"media": {"url": "https://exemplo.com.br/promo.jpg"}, "caption": "Novidades da semana"}'
Os mesmos limites de tamanho e de tipo do envio de mídia valem aqui. O vídeo ainda é um dos recursos em beta da API.
Quais são os limites?
| Regra | Valor |
|---|---|
| Publicações por dia por instância | 3 (padrão); você só pode reduzir |
| Texto | até 700 caracteres |
| Agendar | não pode |
| Ligado por padrão | não |
| Entra no limite de 500 mensagens por dia | não; tem contador próprio |
| Respeita a pausa entre envios e a trava de contato novo | sim |
Passou do teto do dia, a API responde 429 daily_limit com retry_after. O dia conta pelo horário de São Paulo e o contador zera à meia-noite.
Quais erros posso receber?
| HTTP | error |
O que fazer |
|---|---|---|
| 403 | status_disabled |
Ligue status_enabled em /instance/settings |
| 422 | invalid_request |
Texto vazio ou acima de 700, mídia ausente, ou schedule enviado |
| 429 | daily_limit |
Espere o dia seguinte; o teto é de 3 |
| 409 | not_connected |
Leia o QR de novo |
| 409 | new_contacts_locked |
O WhatsApp restringiu o número; veja a restrição 463 |
Mais códigos em erros e limites.
Como fica em Node?
const base = "https://proxybox.com.br/api/whatsapp/v1";
const h = { apikey: process.env.WA_KEY, "Content-Type": "application/json" };
await fetch(`${base}/instance/settings`, { method: "PUT", headers: h, body: JSON.stringify({ status_enabled: true }) });
const r = await fetch(`${base}/status/text`, { method: "POST", headers: h, body: JSON.stringify({ text: "Fechamos às 18h." }) });
console.log(r.status, await r.json());
O MCP e a aprovação humana funcionam com status?
Sim. Se a instância usa a aprovação humana em modo all, o status também espera a liberação. É uma boa proteção quando um assistente de IA (pelo conector MCP) pode propor publicações.
Quando não usar?
Se a ideia é falar com uma lista que você tem em planilha, o status não substitui o consentimento: quem não pediu para receber não deveria ser alcançado. A política de uso aceitável proíbe mensagem em massa e spam, e o status entra nessa regra. A API não oferece escolha de destinatários, lista de transmissão nem publicação em canal.
Veja também
- Botões e listas no WhatsApp via API
- Enviar imagem, vídeo e áudio no WhatsApp via API
- Agendar mensagem de WhatsApp pela API
- Segurança da API de WhatsApp: chave e IPs
Índice completo: todos os guias. Sobre o produto: instância de WhatsApp com chave própria.
Autoria: equipe técnica da ProxyBox. Revisado em 11/11/2026 contra a versão 1.1 da API.