Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Conta e migração

Referência da API de WhatsApp: todas as rotas, com exemplo de pedido e resposta

Todas as rotas da API de WhatsApp com exemplo de pedido e resposta, regras comuns, idempotência e código em Go, Java, C# e Ruby.

57 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
A base é https://proxybox.com.br/api/whatsapp/v1, a chave vai no cabeçalho apikey e toda resposta tem ok verdadeiro ou falso. Este guia traz um pedido em curl e a resposta de cada rota, e código em Go, Java, C# e Ruby para enviar texto, enviar imagem, verificar números, criar grupo e validar o aviso. A especificação completa está em OpenAPI, Postman e status.

Provado em aparelho real em 14/11/2026: conexão por código; bloquear, desbloquear e listar bloqueados; fixar mensagem; convite de evento; quem adiciona membros ao grupo e aprovação de entrada; voto em enquete, toque em botão de resposta e mensagens recebidas (pela consulta de avisos). Retirados depois de testar: botão PIX, recado do perfil e criar comunidade.

Provado em aparelho real em 12/11/2026 (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 (409 opted_out), aprovação humana, agendamento de uma mensagem, etiquetas, ajustes e proteções (IP permitido, status desligado = 403), 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, recusados com 422 interactive_unsupported. Ainda não provados: botão de localização, vídeo, status, grupos além de listar, avisos de mensagens recebidas (voto de enquete, resposta de botão, reação, texto, foto, voz), recusa de chamada, S3, Chatwoot, bots e imagem por URL.

Provado em aparelho real em 10/11/2026: texto, imagem, documento, áudio (voz e arquivo), figurinha, localização, contato, enquete, reação, editar, marcar como lida, encaminhar, apagar para todos, "digitando…", ler conversas, baixar mídia recebida, contatos, perfil, foto, privacidade e listar grupos. Recurso em beta: pode mudar vale para as demais rotas (vídeo, grupos além de listar, canais, pareamento e o restante da versão 1.2). GET /instance mostra a situação de cada rota em capabilities.

Quais são as regras comuns a todas as rotas?

  • Base: https://proxybox.com.br/api/whatsapp/v1
  • Autenticação: cabeçalho apikey: pbwa_… (também aceita Authorization: Bearer pbwa_…). A chave abre uma instância.
  • Formato: JSON em UTF-8; datas em ISO 8601 com fuso. Corpo de até 40 MB nas rotas de mídia.
  • Destino (to): telefone com código do país, com ou sem formatação, ou o id de um grupo (termina em @g.us). Veja número e identidade.
  • Respostas: envio devolve { "ok": true, "id", "to", "status": "sent", "sent_at" }. As demais rotas devolvem { "ok": true, "data": { … } }, com campos em snake_case. As rotas de conexão (qr, pair-code, restart, logout) devolvem os campos na raiz.
  • Erros: { "ok": false, "error": "…", "message": "…" }, com retry_after e fields quando couber. Tabela em erros e limites.
  • Categorias de limite: envio (10 por minuto, 500 por dia), ação (60 por minuto), leitura (120 por minuto), consulta (teto por dia) e administração (tetos por hora e por dia).

Como uso Idempotency-Key?

Em qualquer POST /messages/*, o cabeçalho Idempotency-Key (até 64 caracteres) torna o pedido repetível: a mesma chave em até 24 horas devolve a resposta original, sem enviar de novo.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/text" \
  -H "apikey: SUA_CHAVE" -H "Idempotency-Key: pedido-4512-aviso-entrega" -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","text":"Seu pedido saiu para entrega."}'

Como agendo com schedule?

Todo envio aceita schedule com uma data futura, até 30 dias. A resposta é 202, e a mídia só vale por url. Detalhes em agendar.

bash
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":"Lembrete: sua consulta é amanhã às 9h.","schedule":{"at":"2026-11-12T09:00:00-03:00"}}'
json
{ "ok": true, "schedule_id": 17, "run_at": "2026-11-12T09:00:00-03:00", "status": "pending" }

Como mando uma mensagem temporária com expires_in?

Todo envio aceita expires_in, em segundos: 86400 (24 horas), 604800 (7 dias) ou 7776000 (90 dias). Outro valor devolve 422 invalid_request. A mensagem some do celular da pessoa depois desse prazo.

bash
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":"Seu código é 482910.","expires_in":86400}'

Como vejo o que é estável e o que está em beta?

GET /instance traz capabilities, uma lista com op, status, method e path de cada operação:

json
{ "ok": true, "instance": { "slug": "atendimento-da-loja", "status": "connected", "connected": true }, "passkey": false, "signal": { "level": "ok", "label": "Funcionando", "until": null },
  "capabilities": [ { "op": "send.text", "status": "stable", "method": "POST", "path": "/api/whatsapp/v1/messages/text" }, { "op": "send.image", "status": "beta", "method": "POST", "path": "/api/whatsapp/v1/messages/image" } ] }

Instância e conexão

GET /health

Saúde da instância. Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/health" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "connected": true, "logged_in": true, "roundtrip_ms": 412, "deaf": false } }

GET /instance/info

Informações da instância. Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/instance/info" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "ffmpeg": true } }

GET /instance/qr

QR para conectar o número. Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/instance/qr" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "png_base64": "iVBORw0KGgoAAAANSUhEUg…", "expires_in": 20 }

POST /instance/pair-code

Código para conectar o número. Categoria de limite: ação. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/instance/pair-code" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5547999999999"}'
json
{ "ok": true, "code": "ABCD-1234" }

POST /instance/restart

Reconectar o número. Categoria de limite: ação. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/instance/restart" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "message": "Reconexão pedida. Acompanhe o estado em GET /instance." }

POST /instance/logout

Desconectar o número. Categoria de limite: ação. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/instance/logout" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"confirm":true}'
json
{ "ok": true, "message": "Número desconectado. Leia o QR de novo para voltar." }

GET /instance/settings

Ver os ajustes da instância. Categoria de limite: leitura. Provado em aparelho real em 12/11/2026.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/instance/settings" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "reject_calls": false, "reject_calls_message": null, "delivery_mode": "push", "buffer_seconds": 0, "status_enabled": false, "api_allowlist": [] } }

PUT /instance/settings

Mudar os ajustes da instância. Categoria de limite: ação. Provado em aparelho real em 12/11/2026.

bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/instance/settings" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"reject_calls":true,"reject_calls_message":"Não atendemos ligações por aqui."}'
json
{ "ok": true, "data": { "reject_calls": true, "reject_calls_message": "Não atendemos ligações por aqui." } }

Enviar mensagens

POST /messages/text

Enviar texto. Categoria de limite: envio. Provado em aparelho real em 10/11/2026.

bash
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":"Seu pedido saiu para entrega."}'
json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-11T14:03:22-03:00" }

POST /messages/image

Enviar imagem. Categoria de limite: envio. Provado em aparelho real em 10/11/2026.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/image" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","media":{"url":"https://exemplo.com.br/fotos/pedido-123.jpg"},"caption":"Seu comprovante"}'
json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-11T14:03:22-03:00" }

POST /messages/video

Enviar vídeo. Categoria de limite: envio. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/video" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","media":{"url":"https://exemplo.com.br/videos/tutorial.mp4"},"caption":"Tutorial de uso"}'
json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-11T14:03:22-03:00" }

POST /messages/audio

Enviar áudio. Categoria de limite: envio. Provado em aparelho real em 10/11/2026.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/audio" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","media":{"url":"https://exemplo.com.br/audios/aviso.ogg"},"voice":true}'
json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-11T14:03:22-03:00" }

POST /messages/document

Enviar documento. Categoria de limite: envio. Provado em aparelho real em 10/11/2026.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/document" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","media":{"url":"https://exemplo.com.br/docs/contrato.pdf"},"filename":"contrato.pdf","caption":"Segue o contrato"}'
json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-11T14:03:22-03:00" }

POST /messages/sticker

Enviar figurinha. Categoria de limite: envio. Provado em aparelho real em 10/11/2026.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/sticker" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","media":{"url":"https://exemplo.com.br/figurinhas/ok.webp"}}'
json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-11T14:03:22-03:00" }

POST /messages/location

Enviar localização. Categoria de limite: envio. Provado em aparelho real em 10/11/2026.

bash
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}'
json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-11T14:03:22-03:00" }

POST /messages/contact

Enviar contato. Categoria de limite: envio. Provado em aparelho real em 10/11/2026.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/contact" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","name":"Maria Souza","phone":"5547999998888"}'
json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-11T14:03:22-03:00" }

POST /messages/link

Enviar link. Categoria de limite: envio. Provado em aparelho real em 12/11/2026.

Sai como texto com o endereço, sem prévia do site.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/link" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","url":"https://exemplo.com.br/pedido/123","caption":"Acompanhe o seu pedido"}'
json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-11T14:03:22-03:00" }

POST /messages/poll

Enviar enquete. Categoria de limite: envio. Provado em aparelho real em 10/11/2026.

bash
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}'
json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-11T14:03:22-03:00" }

POST /messages/forward

Encaminhar mensagem. Categoria de limite: envio. Provado em aparelho real em 10/11/2026.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/forward" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","id":"3EB0B430B6F8F1D0E053AC120E0A9E5C"}'
json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-11T14:03:22-03:00" }

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

Ações sobre mensagens, presença e chamadas

POST /messages/{id}/reaction

Reagir a uma mensagem. Categoria de limite: ação. Provado em aparelho real em 10/11/2026.

bash
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":"👍"}'
json
{ "ok": true, "data": {} }

POST /messages/{id}/edit

Editar mensagem. Categoria de limite: ação. Provado em aparelho real em 10/11/2026.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/3EB0B430B6F8F1D0E053AC120E0A9E5C/edit" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"chat":"5547999999999","text":"Seu pedido saiu às 15h."}'
json
{ "ok": true, "data": {} }

POST /messages/{id}/revoke

Apagar para todos. Categoria de limite: ação. Provado em aparelho real em 10/11/2026.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/3EB0B430B6F8F1D0E053AC120E0A9E5C/revoke" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"chat":"5547999999999"}'
json
{ "ok": true, "data": {} }

DELETE /messages/{id}

Apagar só na instância. Categoria de limite: ação. Beta.

bash
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/messages/3EB0B430B6F8F1D0E053AC120E0A9E5C?chat=5547999999999" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": {} }

POST /messages/{id}/read

Marcar como lida. Categoria de limite: ação. Provado em aparelho real em 10/11/2026.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/3EB0B430B6F8F1D0E053AC120E0A9E5C/read" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"chat":"5547999999999"}'
json
{ "ok": true, "data": {} }

POST /messages/{id}/played

Marcar áudio como ouvido. Categoria de limite: ação. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/3EB0B430B6F8F1D0E053AC120E0A9E5C/played" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"chat":"5547999999999"}'
json
{ "ok": true, "data": {} }

POST /messages/{id}/star

Favoritar mensagem. Categoria de limite: ação. Beta.

Instável: às vezes pede para repetir.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/3EB0B430B6F8F1D0E053AC120E0A9E5C/star" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"chat":"5547999999999"}'
json
{ "ok": true, "data": {} }

POST /messages/{id}/unstar

Tirar dos favoritos. Categoria de limite: ação. Beta.

Instável: às vezes pede para repetir.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/3EB0B430B6F8F1D0E053AC120E0A9E5C/unstar" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"chat":"5547999999999"}'
json
{ "ok": true, "data": {} }

POST /typing

Mostrar "digitando…". Categoria de limite: ação. Provado em aparelho real em 10/11/2026.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/typing" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","state":"composing"}'
json
{ "ok": true, "data": {} }

POST /presence

Mostrar online ou offline. Categoria de limite: ação. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/presence" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"state":"available"}'
json
{ "ok": true, "data": {} }

POST /calls/reject

Recusar chamada. Categoria de limite: ação. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/calls/reject" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"from":"5547999999999","call_id":"A1B2C3D4"}'
json
{ "ok": true, "data": {} }

Mídia recebida

GET /messages/{id}/media

Baixar mídia recebida. Categoria de limite: leitura. Provado em aparelho real em 10/11/2026.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/messages/3EB0B430B6F8F1D0E053AC120E0A9E5C/media?chat=5547999999999" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "media_type": "document", "mime": "application/pdf", "filename": "comprovante.pdf", "size": 48211, "base64": "JVBERi0x…" } }

Contatos, perfil e não perturbe

POST /contacts/check

Conferir números no WhatsApp. Categoria de limite: consulta. Beta.

Para número brasileiro a resposta traz note: br_9th_digit_unverified: a consulta não distingue o nono dígito.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/contacts/check" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["5547999999999","5511988887777"]}'
json
{ "ok": true, "data": { "results": [ { "input": "5547999999999", "exists": true, "number": "5547999999999", "jid": "[email protected]", "note": "br_9th_digit_unverified" } ] } }

GET /contacts/{phone}

Dados de um contato. Categoria de limite: consulta. Provado em aparelho real em 10/11/2026.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/contacts/5547999999999" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "name": "Maria", "status": "Disponível", "picture_id": "1730000000", "verified_name": null, "business": false } }

GET /contacts/{phone}/avatar

Foto de um contato. Categoria de limite: consulta. Provado em aparelho real em 10/11/2026.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/contacts/5547999999999/avatar?preview=true" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "url": "https://pps.whatsapp.net/…" } }

GET /contacts/{phone}/business

Perfil comercial de um contato. Categoria de limite: consulta. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/contacts/5547999999999/business" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "email": "[email protected]", "address": "Rua das Flores, 100", "categories": ["Varejo"], "hours": [] } }

GET /contacts

Listar contatos. Categoria de limite: leitura. Provado em aparelho real em 10/11/2026.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/contacts" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "contacts": [ { "jid": "[email protected]", "phone": "5547999999999", "name": "Maria" } ] } }

GET /profile/privacy

Ver a privacidade do perfil. Categoria de limite: leitura. Provado em aparelho real em 10/11/2026.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/profile/privacy" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "group_add": "contacts", "last_seen": "contacts", "status": "all", "profile": "all", "read_receipts": "all" } }

PUT /profile/name

Mudar o nome do perfil. Categoria de limite: ação. Beta.

bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/profile/name" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name":"Loja da Maria"}'
json
{ "ok": true, "data": {} }

PUT /profile/avatar

Mudar a foto do perfil. Categoria de limite: ação. Beta.

bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/profile/avatar" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"media":{"url":"https://exemplo.com.br/logo.png"}}'
json
{ "ok": true, "data": {} }

GET /optout

Ver a lista "não perturbe". Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/optout?limit=50" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "total": 1, "optouts": [ { "phone": "5547999999999", "reason": "pediu para parar", "created_at": "2026-11-11T10:02:11-03:00" } ] } }

POST /optout

Pôr na lista "não perturbe". Categoria de limite: ação. Provado em aparelho real em 12/11/2026.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/optout" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5547999999999","reason":"pediu para parar"}'
json
{ "ok": true, "data": { "phone": "5547999999999", "reason": "pediu para parar", "already": false } }

DELETE /optout/{phone}

Tirar da lista "não perturbe". Categoria de limite: ação. Provado em aparelho real em 12/11/2026.

bash
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/optout/5547999999999" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "phone": "5547999999999" } }

Conversas

GET /chats

Listar conversas. Categoria de limite: leitura. Provado em aparelho real em 10/11/2026.

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-11T13:58:00-03:00", "archived": false } ] } }

GET /chats/{chat}/messages

Ler mensagens de uma conversa. Categoria de limite: leitura. Provado em aparelho real em 10/11/2026.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/chats/5547999999999/messages?limit=20&media_only=false" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "total": 1, "messages": [ { "id": "3EB0A1", "chat": "[email protected]", "sender": "5547999999999", "text": "Segue o comprovante", "at": "2026-11-11T13:57:10-03:00", "from_me": false, "media_type": "document", "filename": "comprovante.pdf", "reactions": [] } ] } }

POST /chats/{chat}/pin

Fixar conversa. Categoria de limite: ação. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/chats/5547999999999/pin" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"value":true}'
json
{ "ok": true, "data": {} }

POST /chats/{chat}/archive

Arquivar conversa. Categoria de limite: ação. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/chats/5547999999999/archive" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"value":true}'
json
{ "ok": true, "data": {} }

POST /chats/{chat}/disappearing

Mensagens temporárias. Categoria de limite: ação. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/chats/5547999999999/disappearing" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"seconds":86400}'
json
{ "ok": true, "data": {} }

POST /chats/{chat}/sync

Pedir histórico da conversa. Categoria de limite: ação. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/chats/5547999999999/sync" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"count":50}'
json
{ "ok": true, "data": { "requested": 50 } }

Grupos

GET /groups

Listar grupos. Categoria de limite: leitura. Provado em aparelho real em 10/11/2026.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/groups" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "groups": [ { "id": "[email protected]", "name": "Pedidos da semana", "size": 12, "owner": "5547999999999", "announce": false, "locked": false } ] } }

GET /groups/{group}

Dados de um grupo. Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "id": "[email protected]", "name": "Pedidos da semana", "topic": "Avisos da loja", "created_at": "2026-10-02T09:00:00-03:00", "announce": false, "locked": false, "participants": [ { "jid": "[email protected]", "phone": "5547999999999", "admin": true, "super_admin": true } ] } }

POST /groups

Criar grupo. Categoria de limite: administração. Beta.

Exige ao menos 1 participante.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/groups" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"title":"Pedido 4512","participants":["5547999999999","5511988887777"]}'
json
{ "ok": true, "data": { "id": "[email protected]" } }

POST /groups/{group}/participants/add

Adicionar ao grupo. Categoria de limite: administração. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/participants/add" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"participants":["5511988887777"]}'
json
{ "ok": true, "data": { "results": [ { "participant": "5547999999999", "ok": true, "message": "" } ] } }

POST /groups/{group}/participants/remove

Tirar do grupo. Categoria de limite: administração. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/participants/remove" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"participants":["5511988887777"]}'
json
{ "ok": true, "data": { "results": [ { "participant": "5547999999999", "ok": true, "message": "" } ] } }

POST /groups/{group}/participants/promote

Tornar administrador. Categoria de limite: administração. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/participants/promote" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"participants":["5511988887777"]}'
json
{ "ok": true, "data": { "results": [ { "participant": "5547999999999", "ok": true, "message": "" } ] } }

POST /groups/{group}/participants/demote

Tirar de administrador. Categoria de limite: administração. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/participants/demote" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"participants":["5511988887777"]}'
json
{ "ok": true, "data": { "results": [ { "participant": "5547999999999", "ok": true, "message": "" } ] } }

PUT /groups/{group}/name

Mudar o nome do grupo. Categoria de limite: administração. Beta.

bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/name" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name":"Clientes VIP"}'
json
{ "ok": true, "data": {} }

PUT /groups/{group}/topic

Mudar a descrição do grupo. Categoria de limite: administração. Beta.

bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/topic" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"topic":"Avisos da loja"}'
json
{ "ok": true, "data": {} }

PUT /groups/{group}/photo

Mudar a foto do grupo. Categoria de limite: administração. Beta.

bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/photo" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"media":{"url":"https://exemplo.com.br/foto-grupo.jpg"}}'
json
{ "ok": true, "data": {} }

PUT /groups/{group}/locked

Só admins editam o grupo. Categoria de limite: administração. Beta.

bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/locked" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"value":true}'
json
{ "ok": true, "data": {} }

PUT /groups/{group}/announce

Só admins enviam mensagens. Categoria de limite: administração. Beta.

bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/announce" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"value":true}'
json
{ "ok": true, "data": {} }

Link de convite do grupo. Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/invite-link?reset=false" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "link": "https://chat.whatsapp.com/AbCdEfGh123" } }

POST /groups/join

Entrar num grupo por link. Categoria de limite: administração. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/groups/join" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"link":"https://chat.whatsapp.com/AbCdEfGh123"}'
json
{ "ok": true, "data": { "id": "[email protected]" } }

GET /groups/preview

Ver um grupo antes de entrar. Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/groups/preview?link=https://chat.whatsapp.com/AbCdEfGh123" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "id": "[email protected]", "name": "Pedidos da semana", "topic": "Avisos da loja", "size": 12 } }

POST /groups/{group}/leave

Sair do grupo. Categoria de limite: administração. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/leave" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": {} }

GET /groups/{group}/requests

Pedidos para entrar no grupo. Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/requests" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "requests": [] } }

POST /groups/{group}/requests/approve

Aprovar pedidos para entrar. Categoria de limite: administração. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/requests/approve" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"participants":["5511988887777"]}'
json
{ "ok": true, "data": { "results": [ { "participant": "5511988887777", "ok": true, "message": "" } ] } }

POST /groups/{group}/requests/reject

Recusar pedidos para entrar. Categoria de limite: administração. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/requests/reject" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"participants":["5511988887777"]}'
json
{ "ok": true, "data": { "results": [ { "participant": "5511988887777", "ok": true, "message": "" } ] } }

Canais

GET /channels

Listar canais. Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/channels" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "channels": [] } }

GET /channels/info

Dados de um canal. Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/channels/info?newsletter_id=120363000000000000@newsletter" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "id": "120363000000000000@newsletter", "name": "Novidades da loja" } }

POST /channels/follow

Seguir canal. Categoria de limite: ação. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/channels/follow" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"newsletter_id":"120363000000000000@newsletter"}'
json
{ "ok": true, "data": {} }

POST /channels/unfollow

Deixar de seguir canal. Categoria de limite: ação. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/channels/unfollow" \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"newsletter_id":"120363000000000000@newsletter"}'
json
{ "ok": true, "data": {} }

GET /channels/messages

Mensagens de um canal. Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/channels/messages?newsletter_id=120363000000000000@newsletter&count=20" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "messages": [] } }

Agendamentos

GET /schedules

Listar mensagens agendadas. Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/schedules?status=pending" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "total": 1, "schedules": [ { "schedule_id": 17, "op": "send.text", "type": "text", "to": "5547999999999", "run_at": "2026-11-12T09:00:00-03:00", "status": "pending", "attempts": 0, "created_at": "2026-11-11T14:00:00-03:00" } ] } }

GET /schedules/{id}

Ver uma mensagem agendada. Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/schedules/17" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "schedule_id": 17, "op": "send.text", "type": "text", "to": "5547999999999", "run_at": "2026-11-12T09:00:00-03:00", "status": "pending", "attempts": 0, "created_at": "2026-11-11T14:00:00-03:00" } }

DELETE /schedules/{id}

Cancelar uma mensagem agendada. Categoria de limite: ação. Beta.

bash
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/schedules/17" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "schedule_id": 17, "status": "canceled" } }

Novidades da versão 1.2: botões, status, avisos por consulta, atividade, etiquetas, aprovação, bots e integrações

Tudo desta seção está em beta: pode mudar, não foi provado em aparelho real e nasce desligado ou sem efeito até você configurar. As rotas aparecem também em GET /instance (capabilities) e na especificação OpenAPI. As rotas de aprovação, bot, Chatwoot, S3 e sandbox são específicas e podem não constar do catálogo das ferramentas.

POST /messages/interactive

Enviar botões de resposta, link, copiar código e ligar. Categoria de limite: envio. Provado em aparelho real em 12/11/2026 (o botão de localização, não). Lista e carrossel não funcionam e são recusados com 422 interactive_unsupported. Detalhes e limites em botões. Não agenda.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/interactive" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","body":"Confirma a entrega amanhã?","buttons":[{"type":"reply","id":"sim","text":"Sim"},{"type":"reply","id":"nao","text":"Não"}]}'
json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "status": "sent", "data": { "rendered": null }, "warning": "O WhatsApp pode aceitar a mensagem e não mostrar os botões." }

Pedido com list ou cards:

json
{ "ok": false, "error": "interactive_unsupported", "message": "Lista e carrossel ainda não funcionam: o WhatsApp mostra \"mensagem incompatível\". Use botões (resposta, link, copiar ou ligar).", "fields": ["buttons"] }

POST /status/text, POST /status/image e POST /status/video

Publicar status. Categoria de limite: status (3 por dia). Beta e desligado por padrão: sem status_enabled nos ajustes, a resposta é 403 status_disabled. Vai para todos os contatos do número. Não agenda. Guia: status.

bash
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}'
json
{ "ok": true, "id": "3EB0A9F2C1D4B6E7F801", "status": "sent", "sent_at": "2026-11-12T09:30:00-03:00" }

GET /events

Consultar avisos novos (modo pull ou both). Parâmetros: after, limit (1 a 100), wait (1 a 25). Categoria de limite: leitura. Provado em aparelho real em 12/11/2026. Guia: receber por consulta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/events?after=0&limit=50&wait=20" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "events": [ { "id": 121, "event": "message.received", "uid": "in_3EB0A1", "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" }, "sent_at": "2026-11-12T10:00:02-03:00", "occurred_at": "2026-11-12T13:00:01Z", "data": { "from": "5547999999999", "type": "text", "text": "Oi" } } ], "next_after": 121, "has_more": false } }

POST /events/ack

Confirmar avisos já processados, até o id informado. Categoria de limite: ação. Provado em aparelho real em 12/11/2026.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/events/ack" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"up_to":121}'
json
{ "ok": true, "data": { "acked": 1 } }

GET /activity

Ver as últimas operações (30 dias, sem o texto das mensagens). Filtros: limit, op, status, before. Categoria de limite: leitura. Beta. Guia: atividade e métricas.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/activity?status=failed&limit=20" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "items": [ { "id": 5821, "op": "send.text", "cat": "send", "via": "api", "http": 429, "error": "rate_limited", "ms": 12, "to_tail4": "9999", "created_at": "2026-11-12T10:03:11-03:00" } ], "next_before": 5821 } }

GET /metrics

Ver o resumo por dia (days de 1 a 30). Categoria de limite: leitura. Beta.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/metrics?days=14" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { "days": [ { "date": "2026-11-12", "sent": 188, "failed": 3 } ], "by_op": { "send.text": 351 }, "by_error": { "rate_limited": 6 }, "avg_ms": 640, "delivered_pct": 99.1, "webhooks": { "ok": 402, "dead": 3, "pending": 0 } } }

Ajustes novos em PUT /instance/settings

Além de reject_calls e reject_calls_message, a versão 1.2 aceita:

Campo Valores Guia
delivery_mode push (padrão), pull, both receber por consulta
buffer_seconds 0 a 30 agrupar mensagens
buffer_replace true ou false idem
status_enabled true ou false status
api_allowlist lista de até 20 IPs ou faixas IPs permitidos
approval_mode off, bots, all aprovação humana
approval_ttl_hours 1 a 72 idem
bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/instance/settings" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"delivery_mode":"both","buffer_seconds":5,"api_allowlist":["203.0.113.7"]}'

GET /labels e POST /labels

Listar e criar etiquetas (até 50 por instância). Categoria de limite: leitura e ação. Provado em aparelho real em 12/11/2026. Guia: etiquetas.

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 } }

DELETE /labels/{id}

Apagar a etiqueta e tirá-la de todas as conversas. Provado em aparelho real em 12/11/2026.

bash
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/labels/3" -H "apikey: SUA_CHAVE"

POST /labels/{id}/chats, DELETE /labels/{id}/chats e GET /labels/{id}/chats

Marcar, desmarcar e listar as conversas de uma etiqueta (até 500). O chat vai no corpo (ou na consulta, no DELETE). GET /chats?label={id} filtra as conversas. Provado em aparelho real em 12/11/2026.

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"}'

GET /approvals, GET /approvals/{id}, POST /approvals/{id}/approve e POST /approvals/{id}/reject

Listar, ver, aprovar e rejeitar mensagens pendentes de aprovação humana. Provado em aparelho real em 12/11/2026. A lista nunca traz o texto nem o número inteiro; o conector de IA não pode decidir.

bash
curl "https://proxybox.com.br/api/whatsapp/v1/approvals?status=pending" -H "apikey: SUA_CHAVE"
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/approvals/41/approve" -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": [ { "id": 41, "op": "send.text", "via": "bot", "requested_by": null, "to_tail4": "9999", "status": "pending", "error": null, "created_at": "2026-11-12T10:00:00-03:00", "expires_at": "2026-11-13T10:00:00-03:00", "decided_at": null } ], "pending": 1 }

GET, PUT e DELETE /integrations/bot, mais POST /integrations/bot/test e /integrations/bot/sessions

Configurar o bot da instância (Typebot, Dify, Flowise, OpenAI e compatíveis, Claude, n8n ou webhook), testar sem enviar e gerenciar as sessões (POST /integrations/bot/sessions/{chat}/reset e /pause). Beta; desligado até você gravar a configuração. Respostas sem segredos inteiros.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/integrations/bot/test" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"text":"Qual o horário de vocês?"}'

GET, PUT e DELETE /integrations/chatwoot e /integrations/s3

Configurar o Chatwoot e o armazenamento S3. Também POST /integrations/{chatwoot|s3}/test (testa sem gravar), POST /integrations/chatwoot/rotate-token e GET /integrations (lista). O PUT é parcial e só grava depois de um teste de conexão bem-sucedido. Beta.

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

POST /sandbox/simulate/receive

Simular uma mensagem recebida no sandbox. Só funciona com a chave de um sandbox. Beta. Limite de 30 chamadas por minuto e 60 simulações por hora.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/sandbox/simulate/receive" \
  -H "apikey: SUA_CHAVE_DO_SANDBOX" -H "Content-Type: application/json" \
  -d '{"from":"5547999999999","text":"Oi, quero saber do pedido"}'

Rotas no estilo da Evolution e da Z-API, e API de conta

As bases https://proxybox.com.br/api/whatsapp/evolution e https://proxybox.com.br/api/whatsapp/zapi/instances/{slug}/token/{chave} têm mapas próprios: migrar da Evolution e migrar da Z-API. Criação de instância por API (/api/v1/whatsapp/instances): em breve; hoje responde 404 not_available e nada é cobrado.

Rotas complementares da versão 1.2, uma a uma

Cada rota abaixo tem pedido e resposta. Os campos de data seguem o OpenAPI; onde o resumo diz { … }, o conteúdo varia com a instância. Todas estão em beta.

GET /approvals/{id}

Ver um pedido de aprovação. Um pedido pelo id. Vencido: o estado muda para expired. Beta.

bash
curl -X GET "https://proxybox.com.br/api/whatsapp/v1/approvals/12" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { … } }

POST /approvals/{id}/approve

Aprovar e enviar. Envia agora, pelas regras de hoje (ritmo, limite do dia, "não perturbe", trava de contato novo, instância conectada). Se o limite ou o estado não deixarem, o pedido continua pendente com error curto e você tenta de novo antes de vencer. Duas aprovações ao mesmo tempo nunca enviam duas vezes. Chamada com o cabeçalho X-ProxyBox-Client: mcp (assistente de IA) recebe 403 forbidden. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/approvals/12/approve" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "approval_id": 12, "status": "sent", "id": "3EB0B430B6F8F1D0E053AC120E0A9E5C", "to": "5547999999999", "sent_at": "2026-11-12T14:03:22-03:00" }

POST /approvals/{id}/reject

Rejeitar. Descarta o pedido; nada é enviado. Mesma regra do assistente de IA: 403 forbidden. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/approvals/12/reject" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "approval_id": 12, "status": "rejected" }

GET /integrations

Ver as integrações (Chatwoot e S3). Estado do Chatwoot e do armazenamento S3 desta instância. Nenhum segredo volta: só os 4 últimos caracteres. Beta.

bash
curl -X GET "https://proxybox.com.br/api/whatsapp/v1/integrations" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { … } }

GET /integrations/bot

Ver o bot da instância (sem segredos) e os tipos aceitos. Estado do bot, sem segredos, e os tipos aceitos (campos por tipo em types). Beta.

bash
curl -X GET "https://proxybox.com.br/api/whatsapp/v1/integrations/bot" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { … } }

PUT /integrations/bot

Criar ou mudar o bot (beta; nasce desligado). Cria ou muda o bot. Nasce DESLIGADO até você mandar enabled: true. A chave e o segredo de assinatura nunca voltam (só os 4 últimos); o segredo de assinatura (n8n e webhook) aparece UMA vez, quando é gerado. Todo envio do bot passa pelo ritmo, pela pausa, pela trava de contato novo e pelo "não perturbe". Endereços de terceiros só https, públicos. Beta.

bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/integrations/bot" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"type": "openai", "url": "https://api.openai.com/v1", "api_key": "sk-...", "model": "gpt-4o-mini", "system_prompt": "Você atende a loja X.", "trigger": "all", "ignore_groups": true, "finish_keywords": ["sair"], "expire_minutes": 30, "delay_seconds": 2, "stop_on_human_minutes": 30, "enabled": true}'
json
{ "ok": true, "data": { … } }

DELETE /integrations/bot

Apagar o bot e as sessões. Apaga o bot, as sessões e as chaves guardadas. Beta.

bash
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/integrations/bot" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { … } }

GET /integrations/bot/sessions

Listar as sessões e as estatísticas de 24 h. Sessões ativas e estatísticas das últimas 24 horas. Beta.

bash
curl -X GET "https://proxybox.com.br/api/whatsapp/v1/integrations/bot/sessions" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { … } }

POST /integrations/bot/sessions/{chat}/pause

Pausar o bot em um chat (minutes=0 volta a responder). minutes pausa o bot neste chat; 0 volta a responder. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/integrations/bot/sessions/5547999999999/pause" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"minutes": 60}'
json
{ "ok": true, "data": { … } }

POST /integrations/bot/sessions/{chat}/reset

Limpar a sessão de um chat. Apaga a memória e a sessão deste chat. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/integrations/bot/sessions/5547999999999/reset" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { … } }

POST /integrations/bot/test

Testar o bot com uma mensagem, sem enviar nada ao WhatsApp. Chama o bot com um texto e mostra as respostas; nada é enviado ao WhatsApp. Limite de 10 por minuto. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/integrations/bot/test" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"text": "Olá, tudo bem?"}'
json
{ "ok": true, "data": { … } }

POST /integrations/chatwoot/rotate-token

Girar o token do webhook do Chatwoot. Gera outro token para o endereço de saída do Chatwoot. O endereço antigo deixa de valer na hora. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/integrations/chatwoot/rotate-token" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { … } }

GET /integrations/{type}

Ver uma integração. Devolve a configuração sem segredos (últimos 4 caracteres). No Chatwoot traz webhook_url, o endereço que você cola no Chatwoot. Beta.

bash
curl -X GET "https://proxybox.com.br/api/whatsapp/v1/integrations/chatwoot" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { … } }

PUT /integrations/{type}

Gravar uma integração. Atualização parcial: segredos omitidos ficam como estão. Gravar exige um teste de conexão OK (o teste é feito na hora; se falhar, 422 com a mensagem). Nasce ligada na primeira gravação. Beta.

bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/integrations/chatwoot" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"url": "https://chat.exemplo.com.br", "account_id": 1, "inbox_id": 3, "api_token": "token-do-chatwoot", "ignore_groups": true}'
json
{ "ok": true, "data": { … } }

DELETE /integrations/{type}

Apagar uma integração. Remove a configuração e os segredos guardados. Beta.

bash
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/integrations/chatwoot" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { … } }

POST /integrations/{type}/test

Testar a conexão. Sem corpo, testa o que está gravado. Com corpo (os mesmos campos de PUT), testa sem gravar. Intervalo mínimo de 3 segundos entre testes. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/integrations/chatwoot/test" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { … } }

POST /labels

Criar etiqueta. Ação leve: até 60 por minuto. Até 50 etiquetas por instância. As etiquetas ficam só aqui na ProxyBox: não aparecem no aplicativo do WhatsApp. Beta.

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"}'
json
{ "ok": true, "data": { … } }

DELETE /labels/{id}/chats

Tirar a etiqueta de uma conversa. Ação leve: até 60 por minuto. Envie "chat" na consulta (?chat=5547999999999) ou no corpo. Beta.

bash
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/labels/12/chats" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { … } }

GET /labels/{id}/chats

Listar as conversas de uma etiqueta. Igual a chat.list com label. Aceita limit, offset, search e archived. Beta.

bash
curl -X GET "https://proxybox.com.br/api/whatsapp/v1/labels/12/chats" \
  -H "apikey: SUA_CHAVE"
json
{ "ok": true, "data": { … } }

POST /status/image

Publicar status de imagem. Publica no seu status do WhatsApp: vai para todos os contatos que têm este número. Vem DESLIGADO: ligue em instance.settings.set com status_enabled=true (sem isso, 403 status_disabled). Limite de 3 por dia (só dá para reduzir). Não pode ser agendado. Beta.

bash
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/arquivo"}}'
json
{ "ok": true, "data": { … } }

POST /status/video

Publicar status de vídeo. Publica no seu status do WhatsApp: vai para todos os contatos que têm este número. Vem DESLIGADO: ligue em instance.settings.set com status_enabled=true (sem isso, 403 status_disabled). Limite de 3 por dia (só dá para reduzir). Não pode ser agendado. Beta.

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/status/video" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"media": {"url": "https://exemplo.com.br/arquivo"}}'
json
{ "ok": true, "data": { … } }

Novidades da versão 1.4: bloquear, silenciar, grupos, canais, privacidade e evento

Estas 16 rotas entram em teste (beta) em 14/11/2026. Provadas em aparelho real em 14/11/2026: bloquear, desbloquear, listar bloqueados, fixar mensagem, convite de evento, quem adiciona membros ao grupo e aprovação de entrada. A privacidade e a criação de canal foram aceitas pelo WhatsApp. As demais têm teste automatizado e ainda não foram provadas em número real. Mudar o recado do perfil e criar comunidade foram testados e o WhatsApp recusou o pedido; por isso essas duas rotas foram retiradas. Todas seguem as regras comuns acima (cabeçalho apikey, resposta com ok). Para saber se uma rota está estável, olhe capabilities em GET /instance.

Bloquear contato

POST /contacts/{phone}/block: Bloqueia o número no WhatsApp da instância. Quem foi bloqueado não consegue escrever para o número.

Campo Tipo Obrigatório O que é
phone phone sim Telefone com DDD.
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/contacts/5547999999999/block' \
  -H 'apikey: pbwa_SUA_CHAVE'

Resposta:

json
{ "ok": true, "data": { } }

Desbloquear contato

POST /contacts/{phone}/unblock: Desbloqueia o número.

Campo Tipo Obrigatório O que é
phone phone sim Telefone com DDD.
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/contacts/5547999999999/unblock' \
  -H 'apikey: pbwa_SUA_CHAVE'

Resposta:

json
{ "ok": true, "data": { } }

Contatos bloqueados

GET /blocked-contacts: Lista os números bloqueados pela instância.

bash
curl -X GET 'https://proxybox.com.br/api/whatsapp/v1/blocked-contacts' \
  -H 'apikey: pbwa_SUA_CHAVE'

Resposta:

json
{ "ok": true, "data": { } }

Silenciar conversa

POST /chats/{chat}/mute: Silencia a conversa no aparelho. Sem seconds, silencia para sempre; com value: false, volta a avisar.

Campo Tipo Obrigatório O que é
chat phone sim Número do contato ou id do grupo.
value bool sim true silencia, false volta a avisar.
seconds int não Segundos (até 1 ano). Vazio silencia para sempre.
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/chats/5547999999999/mute' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"value":true}'

Resposta:

json
{ "ok": true, "data": { } }

Marcar como não lida

POST /chats/{chat}/unread: Marca a conversa como não lida (unread: true) ou como lida (unread: false).

Campo Tipo Obrigatório O que é
chat phone sim Número do contato ou id do grupo.
unread bool sim true marca como não lida, false marca como lida.
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/chats/5547999999999/unread' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"unread":true}'

Resposta:

json
{ "ok": true, "data": { } }

Apagar conversa

DELETE /chats/{chat}: Apaga a conversa do aparelho da instância. Não apaga para a outra pessoa e não tem como desfazer.

Campo Tipo Obrigatório O que é
chat phone sim Número do contato ou id do grupo.
delete_media bool não true apaga também as fotos, vídeos e arquivos da conversa.
bash
curl -X DELETE 'https://proxybox.com.br/api/whatsapp/v1/chats/5547999999999' \
  -H 'apikey: pbwa_SUA_CHAVE'

Resposta:

json
{ "ok": true, "data": { } }

Fixar mensagem na conversa

POST /messages/{message_id}/pin: Fixa a mensagem no alto da conversa por 24 horas, 7 dias (padrão) ou 30 dias. Com value: false, solta.

Campo Tipo Obrigatório O que é
chat phone sim Número do contato ou id do grupo.
message_id string sim O id que você recebeu ao enviar ou no aviso de mensagem recebida.
value bool sim true fixa, false solta.
from_me bool não true se a mensagem foi enviada pela instância.
sender phone não Em grupo, o telefone de quem enviou a mensagem (quando não é sua).
seconds enum não Fica fixada por 24 h (86400), 7 dias (604800) ou 30 dias (2592000). Vazio usa 7 dias.
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/messages/3EB0B430B6F8F1D0E053AC120E0A9E5C/pin' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"chat":"5547999999999","value":true}'

Resposta:

json
{ "ok": true, "data": { } }

Enviar convite de evento

POST /messages/event: Envia um convite de evento com nome, data, horário e, se quiser, local e link de chamada. O início precisa estar no futuro.

Campo Tipo Obrigatório O que é
to phone sim Número com DDD (ou com + e código do país). Para grupo, o id terminado em @g.us.
name string sim Até 100 caracteres.
description string não Até 2.048 caracteres.
start_time string sim Data e hora (ISO 8601), no futuro.
end_time string não Data e hora (ISO 8601), depois do início.
join_link url não Endereço https de quem participa on-line.
location_name string não Nome do local (até 100 caracteres).
latitude float não Do local, de -90 a 90.
longitude float não Do local, de -180 a 180.
extra_guests_allowed bool não true deixa quem confirma levar mais gente.
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/messages/event' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"to":"5547999999999","name":"Aula aberta","start_time":"2026-12-01T10:00:00-03:00"}'

Resposta:

json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053", "to": "5547999999999", "status": "sent", "sent_at": "2026-11-14T10:00:00-03:00" }

Mudar a privacidade

PUT /profile/privacy: Muda uma regra de privacidade do número, como quem vê o "visto por último" ou quem pode colocar o número em grupos.

Campo Tipo Obrigatório O que é
name enum sim groupadd (quem me coloca em grupos), last (visto por último), status, profile (foto), readreceipts (confirmação de leitura), online, calladd (quem me liga), messages.
value enum sim all (todos), contacts (meus contatos), contact_blacklist (contatos, exceto...), none (ninguém), match_last_seen, known.
bash
curl -X PUT 'https://proxybox.com.br/api/whatsapp/v1/profile/privacy' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"name":"last","value":"contacts"}'

Resposta:

json
{ "ok": true, "data": { } }

Grupos da comunidade

GET /communities/{community}/groups: Lista os grupos que fazem parte de uma comunidade.

Campo Tipo Obrigatório O que é
community group sim Id da comunidade (termina em @g.us).
bash
curl -X GET 'https://proxybox.com.br/api/whatsapp/v1/communities/120363025246125000%40g.us/groups' \
  -H 'apikey: pbwa_SUA_CHAVE'

Resposta:

json
{ "ok": true, "data": { } }

Colocar um grupo na comunidade

POST /communities/{community}/groups/link: Coloca um grupo que você administra dentro de uma comunidade.

Campo Tipo Obrigatório O que é
community group sim Id da comunidade (termina em @g.us).
group group sim Id do grupo (termina em @g.us).
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/communities/120363025246125000%40g.us/groups/link' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"group":"[email protected]"}'

Resposta:

json
{ "ok": true, "data": { } }

Tirar um grupo da comunidade

POST /communities/{community}/groups/unlink: Tira um grupo da comunidade. O grupo continua existindo.

Campo Tipo Obrigatório O que é
community group sim Id da comunidade (termina em @g.us).
group group sim Id do grupo (termina em @g.us).
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/communities/120363025246125000%40g.us/groups/unlink' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"group":"[email protected]"}'

Resposta:

json
{ "ok": true, "data": { } }

Criar canal

POST /channels: Cria um canal e devolve o channel_id e o código de convite.

Campo Tipo Obrigatório O que é
name string sim Até 100 caracteres.
description string não Até 500 caracteres.
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/channels' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Novidades da loja"}'

Resposta:

json
{ "ok": true, "data": { } }

Silenciar canal

POST /channels/mute: Silencia ou volta a avisar um canal que a instância segue.

Campo Tipo Obrigatório O que é
newsletter_id string sim Id do canal.
value bool sim true silencia, false volta a avisar.
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/channels/mute' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"newsletter_id":"120363000000000000@newsletter","value":true}'

Resposta:

json
{ "ok": true, "data": { } }

Quem adiciona membros ao grupo

PUT /groups/{group}/member-add-mode: Define quem pode adicionar membros: só administradores (admin_add) ou todos (all_member_add).

Campo Tipo Obrigatório O que é
group group sim Id do grupo (termina em @g.us).
mode enum sim admin_add (só administradores) ou all_member_add (todos os membros).
bash
curl -X PUT 'https://proxybox.com.br/api/whatsapp/v1/groups/120363025246125000%40g.us/member-add-mode' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"mode":"admin_add"}'

Resposta:

json
{ "ok": true, "data": { } }

Aprovar quem pede para entrar

PUT /groups/{group}/join-approval: Liga ou desliga a aprovação de quem pede para entrar no grupo. Os pedidos ficam em GET /groups/{group}/requests.

Campo Tipo Obrigatório O que é
group group sim Id do grupo (termina em @g.us).
value bool sim true liga, false desliga.
bash
curl -X PUT 'https://proxybox.com.br/api/whatsapp/v1/groups/120363025246125000%40g.us/join-approval' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"value":true}'

Resposta:

json
{ "ok": true, "data": { } }

Mais rotas da versão 1.4: PIX, recado, comunidade, presença, etiqueta e status

Rotas em beta acrescentadas em 14/11/2026. Seguem as regras comuns acima (cabeçalho apikey, resposta com ok). Para saber se uma rota está estável, olhe capabilities em GET /instance.

Enviar cobrança PIX (copia e cola)

POST /messages/pix: Envia uma cobrança PIX: a mensagem leva o código "copia e cola", montado pela ProxyBox a partir da sua chave, e o botão Copiar código PIX. Provada em aparelho real em 14/11/2026. A resposta traz o código em data.pix_code. A ProxyBox não confere o pagamento: quem confirma é o seu banco.

Campo Tipo Obrigatório O que é
to phone sim Número com DDD (ou com + e código do país). Não aceita grupo.
body string sim A mensagem que acompanha o botão (até 700 caracteres).
footer string não Até 60 caracteres.
merchant_name string sim Como aparece no código PIX (até 25 caracteres).
key string sim A chave PIX que recebe o pagamento.
key_type enum sim EVP (aleatória), CPF, CNPJ, PHONE ou EMAIL.
city string não Até 15 caracteres. Padrão: SAO PAULO.
amount número não Valor em reais. Vazio deixa quem paga digitar.
reference_id string não Código do seu pedido (letras e números, até 25).
include_code bool não Padrão: sim. O botão "Copiar código PIX" vai sempre.
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/messages/pix' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"to":"5547999999999","body":"Pague seu pedido com PIX.","merchant_name":"Loja da Maria","key":"[email protected]","key_type":"EMAIL"}'

Resposta:

json
{ "ok": true, "id": "3EB0B430B6F8F1D0E053", "data": { "pix_code": "00020101021126..." } }

Mudar o recado do perfil

PUT /profile/about: Muda o recado do perfil (de 1 a 139 caracteres). Provada em aparelho real em 14/11/2026.

Campo Tipo Obrigatório O que é
text string sim De 1 a 139 caracteres.
bash
curl -X PUT 'https://proxybox.com.br/api/whatsapp/v1/profile/about' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"text":"Atendimento de 9h às 18h"}'

Resposta:

json
{ "ok": true, "data": { } }

Criar comunidade

POST /communities: Cria uma comunidade. O grupo de avisos é criado automaticamente pelo WhatsApp. Provada em aparelho real em 14/11/2026.

Campo Tipo Obrigatório O que é
name string sim Até 25 caracteres.
description string não Até 500 caracteres.
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/communities' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Clientes da loja"}'

Resposta:

json
{ "ok": true, "data": { } }

Acompanhar se um contato está online

POST /presence/subscribe: Passa a acompanhar se um contato está online. Os avisos chegam como presence.update (from, state igual a online ou offline e, quando a pessoa deixa, last_seen). Só chega de quem foi assinado, e não chega de quem escondeu o "online" nas configurações do WhatsApp. O aviso de offline foi provado em aparelho real em 14/11/2026.

Campo Tipo Obrigatório O que é
to phone sim Telefone com DDD de quem você quer acompanhar. Os avisos chegam como presence.update, só para quem foi assinado, e só se a pessoa não escondeu o "online" nas configurações dela.
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/presence/subscribe' \
  -H 'apikey: pbwa_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{"to":"5547999999999"}'

Resposta:

json
{ "ok": true, "data": { } }

Mudar a minha etiqueta no grupo

POST /groups/{group}/member-label: Muda a etiqueta que aparece ao lado do nome do número da instância dentro de um grupo. Texto vazio remove a etiqueta.

Campo Tipo Obrigatório O que é
group group sim Id do grupo (termina em @g.us).
label string não O texto que aparece ao lado do seu nome neste grupo (até 30 caracteres). Vazio remove.
bash
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/groups/120363025246125000%40g.us/member-label' \
  -H 'apikey: pbwa_SUA_CHAVE'

Resposta:

json
{ "ok": true, "data": { } }

Apagar um status publicado

DELETE /status/{id}: Apaga um status publicado pela instância, pelo id devolvido na publicação.

Campo Tipo Obrigatório O que é
id string sim O id devolvido quando o status foi publicado.
bash
curl -X DELETE 'https://proxybox.com.br/api/whatsapp/v1/status/3EB0C767D82B1A3F0E12' \
  -H 'apikey: pbwa_SUA_CHAVE'

Resposta:

json
{ "ok": true, "data": { } }

Vídeo redondo e avisos por SSE

  • Vídeo redondo: POST /messages/video aceita round: true e envia o vídeo como mensagem de vídeo (a bolinha), sem legenda. Use vídeo curto e quadrado.
  • Avisos por SSE: GET /events/stream entrega os mesmos avisos de GET /events, empurrados em conexões de até 25 segundos. Veja receber por consulta.

Como faço os cinco usos principais em Go, Java, C# e Ruby?

Os exemplos são curtos e sem dependências: só a biblioteca padrão de cada linguagem. Em todos, a chave vem de uma variável de ambiente (WA_KEY) e o segredo do aviso de WA_SEGREDO. Os cinco usos: enviar texto, enviar imagem, verificar números, criar um grupo e receber e validar o aviso. A validação usa o corpo bruto, como explicado no guia de aviso automático.

Go

go
package main

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"math"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

const base = "https://proxybox.com.br/api/whatsapp/v1"

func chamar(metodo, caminho string, corpo any, idem string) (int, string, error) {
	var r io.Reader
	if corpo != nil {
		b, _ := json.Marshal(corpo)
		r = bytes.NewReader(b)
	}
	req, _ := http.NewRequest(metodo, base+caminho, r)
	req.Header.Set("apikey", os.Getenv("WA_KEY"))
	req.Header.Set("Content-Type", "application/json")
	if idem != "" {
		req.Header.Set("Idempotency-Key", idem)
	}
	resp, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)
	if err != nil {
		return 0, "", err
	}
	defer resp.Body.Close()
	b, _ := io.ReadAll(resp.Body)
	return resp.StatusCode, string(b), nil
}

// Receber e validar o aviso: use no seu servidor HTTP.
func confere(header string, corpoBruto []byte, segredo string) bool {
	p := map[string]string{}
	for _, kv := range strings.Split(header, ",") {
		if x := strings.SplitN(kv, "=", 2); len(x) == 2 {
			p[x[0]] = x[1]
		}
	}
	t, err := strconv.ParseInt(p["t"], 10, 64)
	if err != nil || math.Abs(float64(time.Now().Unix()-t)) > 300 {
		return false
	}
	m := hmac.New(sha256.New, []byte(segredo))
	m.Write([]byte(p["t"] + "."))
	m.Write(corpoBruto)
	return hmac.Equal([]byte(hex.EncodeToString(m.Sum(nil))), []byte(p["v1"]))
}

func aviso(w http.ResponseWriter, r *http.Request) {
	corpo, _ := io.ReadAll(r.Body)
	if !confere(r.Header.Get("X-ProxyBox-Signature"), corpo, os.Getenv("WA_SEGREDO")) {
		http.Error(w, "assinatura inválida", http.StatusUnauthorized)
		return
	}
	w.WriteHeader(http.StatusOK) // responda 2xx logo e processe depois
}

func main() {
	// 1. enviar texto
	fmt.Println(chamar("POST", "/messages/text", map[string]any{"to": "5547999999999", "text": "Olá!"}, "pedido-1"))
	// 2. enviar imagem por endereço
	fmt.Println(chamar("POST", "/messages/image", map[string]any{"to": "5547999999999", "media": map[string]string{"url": "https://exemplo.com.br/foto.jpg"}, "caption": "Seu pedido"}, ""))
	// 3. verificar números
	fmt.Println(chamar("POST", "/contacts/check", map[string]any{"numbers": []string{"5547999999999"}}, ""))
	// 4. criar grupo
	fmt.Println(chamar("POST", "/groups", map[string]any{"title": "Pedido 4512", "participants": []string{"5547999999999"}}, ""))
	// 5. receber o aviso
	http.HandleFunc("/whatsapp", aviso)
	http.ListenAndServe(":8080", nil)
}

Java

java
import java.net.URI;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.HexFormat;

public class WhatsApp {
    static final String BASE = "https://proxybox.com.br/api/whatsapp/v1";
    static final HttpClient http = HttpClient.newHttpClient();

    static String chamar(String metodo, String caminho, String json, String idem) throws Exception {
        HttpRequest.Builder b = HttpRequest.newBuilder(URI.create(BASE + caminho))
            .header("apikey", System.getenv("WA_KEY"))
            .header("Content-Type", "application/json")
            .method(metodo, json == null ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(json));
        if (idem != null) b.header("Idempotency-Key", idem);
        HttpResponse<String> r = http.send(b.build(), HttpResponse.BodyHandlers.ofString());
        return r.statusCode() + " " + r.body();
    }

    // Receber e validar o aviso: chame com o cabeçalho X-ProxyBox-Signature e o corpo bruto.
    static boolean confere(String header, byte[] corpoBruto, String segredo) throws Exception {
        String t = null, v1 = null;
        for (String kv : header.split(",")) {
            String[] x = kv.split("=", 2);
            if (x[0].equals("t")) t = x[1];
            if (x[0].equals("v1")) v1 = x[1];
        }
        if (t == null || v1 == null || Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(t)) > 300) return false;
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(segredo.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        mac.update((t + ".").getBytes(StandardCharsets.UTF_8));
        String esperado = HexFormat.of().formatHex(mac.doFinal(corpoBruto));
        return java.security.MessageDigest.isEqual(esperado.getBytes(), v1.getBytes());
    }

    public static void main(String[] a) throws Exception {
        // 1. enviar texto
        System.out.println(chamar("POST", "/messages/text", "{\"to\":\"5547999999999\",\"text\":\"Olá!\"}", "pedido-1"));
        // 2. enviar imagem por endereço
        System.out.println(chamar("POST", "/messages/image", "{\"to\":\"5547999999999\",\"media\":{\"url\":\"https://exemplo.com.br/foto.jpg\"},\"caption\":\"Seu pedido\"}", null));
        // 3. verificar números
        System.out.println(chamar("POST", "/contacts/check", "{\"numbers\":[\"5547999999999\"]}", null));
        // 4. criar grupo
        System.out.println(chamar("POST", "/groups", "{\"title\":\"Pedido 4512\",\"participants\":[\"5547999999999\"]}", null));
    }
}

C#

csharp
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;

var http = new HttpClient { BaseAddress = new Uri("https://proxybox.com.br/api/whatsapp/v1/") };
http.DefaultRequestHeaders.Add("apikey", Environment.GetEnvironmentVariable("WA_KEY"));

async Task<string> Chamar(HttpMethod metodo, string caminho, string? json = null, string? idem = null)
{
    var req = new HttpRequestMessage(metodo, caminho);
    if (json != null) req.Content = new StringContent(json, Encoding.UTF8, "application/json");
    if (idem != null) req.Headers.Add("Idempotency-Key", idem);
    var r = await http.SendAsync(req);
    return (int)r.StatusCode + " " + await r.Content.ReadAsStringAsync();
}

// Receber e validar o aviso: header = X-ProxyBox-Signature, corpoBruto = bytes do corpo
bool Confere(string header, byte[] corpoBruto, string segredo)
{
    var p = header.Split(',').Select(x => x.Split('=', 2)).ToDictionary(x => x[0], x => x[1]);
    if (!p.TryGetValue("t", out var t) || !p.TryGetValue("v1", out var v1)) return false;
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(t)) > 300) return false;
    using var mac = new HMACSHA256(Encoding.UTF8.GetBytes(segredo));
    var esperado = Convert.ToHexString(mac.ComputeHash(Encoding.UTF8.GetBytes(t + ".").Concat(corpoBruto).ToArray())).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(esperado), Encoding.UTF8.GetBytes(v1));
}

// 1. enviar texto
Console.WriteLine(await Chamar(HttpMethod.Post, "messages/text", "{\"to\":\"5547999999999\",\"text\":\"Olá!\"}", "pedido-1"));
// 2. enviar imagem por endereço
Console.WriteLine(await Chamar(HttpMethod.Post, "messages/image", "{\"to\":\"5547999999999\",\"media\":{\"url\":\"https://exemplo.com.br/foto.jpg\"},\"caption\":\"Seu pedido\"}"));
// 3. verificar números
Console.WriteLine(await Chamar(HttpMethod.Post, "contacts/check", "{\"numbers\":[\"5547999999999\"]}"));
// 4. criar grupo
Console.WriteLine(await Chamar(HttpMethod.Post, "groups", "{\"title\":\"Pedido 4512\",\"participants\":[\"5547999999999\"]}"));

Ruby

ruby
require "net/http"
require "json"
require "openssl"

BASE = "https://proxybox.com.br/api/whatsapp/v1"

def chamar(metodo, caminho, corpo = nil, idem = nil)
  uri = URI(BASE + caminho)
  req = Net::HTTP.const_get(metodo.capitalize).new(uri)
  req["apikey"] = ENV["WA_KEY"]
  req["Content-Type"] = "application/json"
  req["Idempotency-Key"] = idem if idem
  req.body = corpo.to_json if corpo
  res = Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 60) { |h| h.request(req) }
  "#{res.code} #{res.body}"
end

# Receber e validar o aviso: header = X-ProxyBox-Signature, corpo_bruto = String do corpo
def confere(header, corpo_bruto, segredo)
  p = header.split(",").map { |kv| kv.split("=", 2) }.to_h
  return false if p["t"].nil? || p["v1"].nil?
  return false if (Time.now.to_i - p["t"].to_i).abs > 300
  esperado = OpenSSL::HMAC.hexdigest("SHA256", segredo, "#{p["t"]}.#{corpo_bruto}")
  OpenSSL.fixed_length_secure_compare(esperado, p["v1"]) rescue false
end

# 1. enviar texto
puts chamar("POST", "/messages/text", { to: "5547999999999", text: "Olá!" }, "pedido-1")
# 2. enviar imagem por endereço
puts chamar("POST", "/messages/image", { to: "5547999999999", media: { url: "https://exemplo.com.br/foto.jpg" }, caption: "Seu pedido" })
# 3. verificar números
puts chamar("POST", "/contacts/check", { numbers: ["5547999999999"] })
# 4. criar grupo
puts chamar("POST", "/groups", { title: "Pedido 4512", participants: ["5547999999999"] })

Onde estão os exemplos em Node, Python e PHP?

Os exemplos nessas três linguagens, mais um cliente mínimo de cada uma, estão nos SDKs e nos primeiros passos (texto), em enviar mídia (imagem e documento), em contatos (verificar números), em grupos (criar grupo) e em aviso automático (validar a assinatura). O mapa para quem vem da Evolution está em migrar da Evolution.

Veja também

Índice completo: índice dos guias. Sobre o produto: API de WhatsApp com IP brasileiro dedicado.

Autoria: equipe técnica da ProxyBox. Atualizado em 14/11/2026. Rotas conforme o catálogo da versão 1.4 (110 operações), revisadas em 11/11/2026; os exemplos de código não foram executados contra a API real, que ainda não está aberta.

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