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

Como ler conversas, baixar mídia recebida e etiquetar chats?

Listar conversas, ler mensagens, baixar a mídia que o cliente mandou e organizar com etiquetas próprias pela API de WhatsApp, e o que pode falhar.

10 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Liste conversas com GET /chats, leia mensagens com GET /chats/{chat}/messages e baixe a mídia recebida com GET /messages/{id}/media?chat=…, até 16 MB. O histórico é o que a instância guardou desde que foi conectada, e o download de mídia antiga pode falhar. Uma seção própria mostra como etiquetar conversas (até 50 etiquetas por instância, só na ProxyBox, sem aparecer no aplicativo do WhatsApp).

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.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/chats?limit=20&offset=0" -H "apikey: SUA_CHAVE"
json
{ "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
json
{ "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:

bash
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:

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_found ou media_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.

js
// 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átis

Como 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?

bash
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"}'
json
{ "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?

bash
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?

bash
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.

bash
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:

bash
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?

bash
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?

python
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)
js
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

Í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.

Perguntas frequentes

As etiquetas aparecem no aplicativo do WhatsApp Business?
Não. Elas ficam só na ProxyBox. O celular do número não vê as etiquetas criadas pela API, e as que você criou no aplicativo do Business não são importadas.
Posso etiquetar um grupo?
Sim. O campo chat aceita o telefone de um contato ou o id de um grupo (termina em @g.us).
Apagar a etiqueta apaga a conversa?
Não. Apagar a etiqueta só a tira de todas as conversas.

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