Provado em aparelho real em 10/11/2026: listar conversas, ler mensagens e baixar mídia recebida. Beta: pode mudar: fixar, arquivar, mensagens temporárias e pedir histórico. O download de mídia antiga pode falhar, e este guia explica por quê.
Atualização de 12/11/2026 (provado em aparelho real): ler conversa e as etiquetas foram provadas pela API pública.
Até aqui, os guias trataram de enviar. Este trata de ler: quais conversas existem, o que foi dito e como pegar a foto, o áudio ou o PDF que o cliente mandou. As rotas são somente de leitura (exceto fixar, arquivar e tempo das mensagens, que mudam a conversa). A base é https://proxybox.com.br/api/whatsapp/v1, com a chave em apikey.
Como listo as conversas?
Com GET /chats, com limit (até 100), offset, search e archived.
curl "https://proxybox.com.br/api/whatsapp/v1/chats?limit=20&offset=0" -H "apikey: SUA_CHAVE"
{ "ok": true, "data": { "total": 134, "chats": [ { "jid": "[email protected]", "name": "Maria", "last_at": "2026-11-10T13:58:00-03:00", "archived": false } ] } }
Parâmetros: limit (até 100), offset (para paginar), search (parte do nome) e archived (true mostra as arquivadas).
Como leio as mensagens de uma conversa?
Com GET /chats/{chat}/messages, filtrando por data, tipo, autor e texto.
GET /chats/{chat}/messages recebe o identificador da conversa: o jid devolvido por /chats, o telefone ou o id do grupo.
| Parâmetro | Para que serve |
|---|---|
limit e offset |
Paginação (até 100 por página) |
from e to |
Intervalo de datas (ISO 8601) |
media_only |
true traz só mensagens com mídia |
from_me |
true só as suas, false só as do outro lado |
search |
Texto contido na mensagem |
{ "ok": true, "data": { "total": 2, "messages": [
{ "id": "3EB0…", "chat": "[email protected]", "sender": "5547999999999", "text": "Segue o comprovante", "at": "2026-11-10T13:57:10-03:00", "from_me": false, "media_type": "document", "filename": "comprovante.pdf", "reactions": [] }
] } }
Como baixo a mídia que o cliente enviou?
Com GET /messages/{id}/media?chat=…, que devolve o arquivo; acrescente as=json para receber o arquivo em base64.
Para mensagens com media_type (imagem, vídeo, áudio, voz, documento, figurinha), use o id e o chat:
curl "https://proxybox.com.br/api/whatsapp/v1/messages/3EB0…/[email protected]" \
-H "apikey: SUA_CHAVE" -o comprovante.pdf
A resposta é o arquivo em binário, com o tipo e o nome corretos nos cabeçalhos. Se preferir JSON com o arquivo em base64, acrescente &as=json:
{ "ok": true, "data": { "media_type": "document", "mime": "application/pdf", "filename": "comprovante.pdf", "size": 48211, "base64": "JVBERi0x…" } }
O limite é de 16 MB por arquivo. A API nunca devolve caminhos internos do servidor: ou entrega o arquivo ou devolve um erro tratado.
Quando o download pode falhar?
- Mídia antiga. O WhatsApp remove os arquivos dos servidores dele depois de um tempo. Se a mensagem é velha, o download pode falhar com
not_foundoumedia_unavailable. - Arquivo acima de 16 MB. Devolve
media_too_large. - Instância desconectada. Devolve
not_connected(409).
A forma segura é baixar na hora: o aviso automático message.received traz o tipo e o tamanho da mídia (media: mime, filename, size) sem o arquivo; o seu sistema chama esta rota e guarda o arquivo.
// dentro do seu receptor do aviso (depois de conferir a assinatura)
if (evento.event === "message.received" && evento.data.media) {
const url = `https://proxybox.com.br/api/whatsapp/v1/messages/${evento.data.id}/media?chat=${(evento.data.group?.id ?? evento.data.from)}`;
const r = await fetch(url, { headers: { apikey: process.env.WA_KEY } });
if (r.ok) await salvar(Buffer.from(await r.arrayBuffer()), evento.data.media.filename);
}
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 fixo, arquivo e ligo mensagens temporárias?
Com POST /chats/{chat}/pin, archive, disappearing e sync, todas ações leves de 60 por minuto.
Ações leves (60 por minuto), com POST:
| Rota | Corpo | O que faz |
|---|---|---|
/chats/{chat}/pin |
value (true/false) |
Fixa ou solta a conversa |
/chats/{chat}/archive |
value |
Arquiva ou desarquiva |
/chats/{chat}/disappearing |
seconds (0, 86400, 604800 ou 7776000) |
Mensagens temporárias: desligado, 24 horas, 7 dias ou 90 dias |
/chats/{chat}/sync |
count (até 500) |
Pede ao celular mais histórico da conversa |
O sync é um pedido: o WhatsApp decide se envia o histórico, e o resultado depende do celular do número. Não há garantia de que o histórico chegue.
Quais são os limites?
Leituras: 120 por minuto. Ações (fixar, arquivar): 60 por minuto.
Leituras têm teto de 120 por minuto por instância, e as ações de fixar e arquivar, 60 por minuto. Detalhes em erros e limites.
Que cuidados tomo com dados de clientes?
As mensagens que você lê aqui são conversas de pessoas. Guarde só o que precisa, proteja o acesso e respeite a política de privacidade e a LGPD no seu sistema.
Como etiqueto conversas?
Resposta curta: crie etiquetas com POST /labels (name e color), marque uma conversa com POST /labels/{id}/chats (chat), tire com DELETE /labels/{id}/chats?chat=…, liste com GET /labels e filtre as conversas com GET /chats?label={id}. O limite é de 50 etiquetas por instância e 500 conversas por etiqueta. As etiquetas são da ProxyBox: não aparecem no aplicativo do WhatsApp.
Recurso em beta: pode mudar. Os nomes dos campos de resposta podem ganhar acréscimos.
Para que servem?
Para o seu sistema ou a sua equipe saberem em que pé está cada conversa sem criar uma tabela à parte: "Cliente VIP", "Aguardando pagamento", "Pedir avaliação". Como a ProxyBox guarda a etiqueta na instância, ela vale para o painel, para a API e para o conector MCP ao mesmo tempo, e você filtra a lista de conversas por ela.
Se você usa o aplicativo do WhatsApp Business no celular e quer as mesmas etiquetas lá, esta API não faz essa sincronização: etiquetas nativas do aplicativo não são lidas nem escritas.
Como crio uma etiqueta?
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/labels" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"name": "Cliente VIP", "color": "green"}'
{ "ok": true, "data": { "id": 3, "name": "Cliente VIP", "color": "green", "chats": 0 } }
O nome tem de 1 a 40 caracteres e não repete na mesma instância. As cores são gray (padrão), red, orange, yellow, green, teal, blue, indigo, purple, pink, brown e black. O limite é de 50 etiquetas por instância.
Como marco uma conversa?
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/labels/3/chats" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"chat": "5547999999999"}'
Marcar de novo a mesma conversa não faz nada (não dá erro). Cada etiqueta aceita até 500 conversas. Para um grupo, use o id terminado em @g.us.
Como tiro a etiqueta de uma conversa?
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/labels/3/chats?chat=5547999999999" \
-H "apikey: SUA_CHAVE"
O chat pode ir na consulta (como acima) ou no corpo.
Como listo as etiquetas e as conversas de cada uma?
GET /labels devolve as etiquetas com a contagem de conversas. GET /labels/{id}/chats devolve as conversas marcadas.
curl "https://proxybox.com.br/api/whatsapp/v1/labels" -H "apikey: SUA_CHAVE"
curl "https://proxybox.com.br/api/whatsapp/v1/labels/3/chats" -H "apikey: SUA_CHAVE"
Como filtro as conversas por etiqueta?
Passando label com o id em GET /chats:
curl "https://proxybox.com.br/api/whatsapp/v1/chats?label=3&limit=50" -H "apikey: SUA_CHAVE"
Há uma ressalva importante. A lista de conversas vem do WhatsApp, e a ProxyBox cruza com as etiquetas lendo até 10 páginas de 100 conversas recentes. Por isso a resposta traz:
complete: verdadeiro se a leitura chegou ao fim das conversas;scanned: quantas conversas foram examinadas;not_listed: etiquetadas que não apareceram na leitura recente (por exemplo, conversas muito antigas).
Se complete for falso, o filtro pode não mostrar todas as conversas da etiqueta. Para a lista exata, use GET /labels/{id}/chats.
Como apago uma etiqueta?
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/labels/3" -H "apikey: SUA_CHAVE"
A etiqueta some e é tirada de todas as conversas. As conversas e as mensagens não mudam.
Como uso em Python e em Node?
import os, requests
B = "https://proxybox.com.br/api/whatsapp/v1"
H = {"apikey": os.environ["WA_KEY"]}
etq = requests.post(f"{B}/labels", headers=H, json={"name": "Pago", "color": "blue"}, timeout=30).json()["data"]
requests.post(f"{B}/labels/{etq['id']}/chats", headers=H, json={"chat": "5547999999999"}, timeout=30)
const B = "https://proxybox.com.br/api/whatsapp/v1";
const H = { apikey: process.env.WA_KEY, "Content-Type": "application/json" };
const { data } = await (await fetch(`${B}/labels`, { method: "POST", headers: H, body: JSON.stringify({ name: "Pago", color: "blue" }) })).json();
await fetch(`${B}/labels/${data.id}/chats`, { method: "POST", headers: H, body: JSON.stringify({ chat: "5547999999999" }) });
Um uso típico: pedido pago
No fluxo do n8n, quando o pagamento é confirmado: envie a mensagem de confirmação e, no passo seguinte, marque a conversa com a etiqueta "Pago". No painel, a equipe filtra por essa etiqueta para ver quem já pagou. Veja outros fluxos nos modelos prontos.
Que convenções de nome funcionam bem?
Etiquetas curtas e de significado único se mantêm úteis: uma etiqueta por estado ("Aguardando pagamento", "Pago", "Pedir avaliação") e outra por tipo de cliente ("VIP", "Atacado"). Evite misturar os dois numa só. Como cada instância aceita 50 etiquetas e 500 conversas por etiqueta, pense nos números antes de usar uma etiqueta como "todos os clientes": ela chega ao teto. E lembre que a etiqueta é um recurso de organização, não de envio: não existe rota que mande mensagem "para todas as conversas da etiqueta", porque isso seria mensagem em massa, proibida pela política de uso aceitável.
Erros e limites
| HTTP | error |
Quando |
|---|---|---|
| 422 | invalid_request |
Nome vazio ou acima de 40, cor fora da lista, repetido ou acima do limite de 50 etiquetas |
| 404 | not_found |
Etiqueta inexistente nesta instância |
| 422 | invalid_request |
Etiqueta com 500 conversas |
As operações de etiqueta são locais da ProxyBox: funcionam mesmo com o número desconectado e não consomem o limite de envio. Veja a tabela completa em erros e limites.
Veja também
- Guardar mídia do WhatsApp no S3, R2 ou MinIO
- Webhook da API de WhatsApp: eventos e assinatura
- Chatwoot com WhatsApp: ligar pela API
- 13 modelos para a API de WhatsApp (Woo, Asaas)
Índice completo: índice dos guias. Sobre o produto: API de WhatsApp com IP brasileiro dedicado.
Autoria: equipe técnica da ProxyBox. Revisado em 11/11/2026 contra a versão 1.1 da API.