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 (409opted_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 com422 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 /instancemostra a situação de cada rota emcapabilities.
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 aceitaAuthorization: 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 oidde 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": "…" }, comretry_afterefieldsquando 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.
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.
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"}}'
{ "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.
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:
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/health" \
-H "apikey: SUA_CHAVE"
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/instance/info" \
-H "apikey: SUA_CHAVE"
{ "ok": true, "data": { "ffmpeg": true } }
GET /instance/qr
QR para conectar o número. Categoria de limite: leitura. Beta.
curl "https://proxybox.com.br/api/whatsapp/v1/instance/qr" \
-H "apikey: SUA_CHAVE"
{ "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.
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"}'
{ "ok": true, "code": "ABCD-1234" }
POST /instance/restart
Reconectar o número. Categoria de limite: ação. Beta.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/instance/restart" \
-H "apikey: SUA_CHAVE"
{ "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.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/instance/logout" \
-H "apikey: SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"confirm":true}'
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/instance/settings" \
-H "apikey: SUA_CHAVE"
{ "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.
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."}'
{ "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.
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."}'
{ "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.
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"}'
{ "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.
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"}'
{ "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.
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}'
{ "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.
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"}'
{ "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.
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"}}'
{ "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.
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}'
{ "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.
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"}'
{ "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.
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"}'
{ "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.
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}'
{ "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.
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"}'
{ "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átisAçõ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.
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":"👍"}'
{ "ok": true, "data": {} }
POST /messages/{id}/edit
Editar mensagem. Categoria de limite: ação. Provado em aparelho real em 10/11/2026.
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."}'
{ "ok": true, "data": {} }
POST /messages/{id}/revoke
Apagar para todos. Categoria de limite: ação. Provado em aparelho real em 10/11/2026.
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"}'
{ "ok": true, "data": {} }
DELETE /messages/{id}
Apagar só na instância. Categoria de limite: ação. Beta.
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/messages/3EB0B430B6F8F1D0E053AC120E0A9E5C?chat=5547999999999" \
-H "apikey: SUA_CHAVE"
{ "ok": true, "data": {} }
POST /messages/{id}/read
Marcar como lida. Categoria de limite: ação. Provado em aparelho real em 10/11/2026.
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"}'
{ "ok": true, "data": {} }
POST /messages/{id}/played
Marcar áudio como ouvido. Categoria de limite: ação. Beta.
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"}'
{ "ok": true, "data": {} }
POST /messages/{id}/star
Favoritar mensagem. Categoria de limite: ação. Beta.
Instável: às vezes pede para repetir.
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"}'
{ "ok": true, "data": {} }
POST /messages/{id}/unstar
Tirar dos favoritos. Categoria de limite: ação. Beta.
Instável: às vezes pede para repetir.
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"}'
{ "ok": true, "data": {} }
POST /typing
Mostrar "digitando…". Categoria de limite: ação. Provado em aparelho real em 10/11/2026.
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"}'
{ "ok": true, "data": {} }
POST /presence
Mostrar online ou offline. Categoria de limite: ação. Beta.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/presence" \
-H "apikey: SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"state":"available"}'
{ "ok": true, "data": {} }
POST /calls/reject
Recusar chamada. Categoria de limite: ação. Beta.
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"}'
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/messages/3EB0B430B6F8F1D0E053AC120E0A9E5C/media?chat=5547999999999" \
-H "apikey: SUA_CHAVE"
{ "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.
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"]}'
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/contacts/5547999999999" \
-H "apikey: SUA_CHAVE"
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/contacts/5547999999999/avatar?preview=true" \
-H "apikey: SUA_CHAVE"
{ "ok": true, "data": { "url": "https://pps.whatsapp.net/…" } }
GET /contacts/{phone}/business
Perfil comercial de um contato. Categoria de limite: consulta. Beta.
curl "https://proxybox.com.br/api/whatsapp/v1/contacts/5547999999999/business" \
-H "apikey: SUA_CHAVE"
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/contacts" \
-H "apikey: SUA_CHAVE"
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/profile/privacy" \
-H "apikey: SUA_CHAVE"
{ "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.
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"}'
{ "ok": true, "data": {} }
PUT /profile/avatar
Mudar a foto do perfil. Categoria de limite: ação. Beta.
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"}}'
{ "ok": true, "data": {} }
GET /optout
Ver a lista "não perturbe". Categoria de limite: leitura. Beta.
curl "https://proxybox.com.br/api/whatsapp/v1/optout?limit=50" \
-H "apikey: SUA_CHAVE"
{ "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.
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"}'
{ "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.
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/optout/5547999999999" \
-H "apikey: SUA_CHAVE"
{ "ok": true, "data": { "phone": "5547999999999" } }
Conversas
GET /chats
Listar conversas. Categoria de limite: leitura. Provado em aparelho real em 10/11/2026.
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-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.
curl "https://proxybox.com.br/api/whatsapp/v1/chats/5547999999999/messages?limit=20&media_only=false" \
-H "apikey: SUA_CHAVE"
{ "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.
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}'
{ "ok": true, "data": {} }
POST /chats/{chat}/archive
Arquivar conversa. Categoria de limite: ação. Beta.
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}'
{ "ok": true, "data": {} }
POST /chats/{chat}/disappearing
Mensagens temporárias. Categoria de limite: ação. Beta.
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}'
{ "ok": true, "data": {} }
POST /chats/{chat}/sync
Pedir histórico da conversa. Categoria de limite: ação. Beta.
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}'
{ "ok": true, "data": { "requested": 50 } }
Grupos
GET /groups
Listar grupos. Categoria de limite: leitura. Provado em aparelho real em 10/11/2026.
curl "https://proxybox.com.br/api/whatsapp/v1/groups" \
-H "apikey: SUA_CHAVE"
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]" \
-H "apikey: SUA_CHAVE"
{ "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.
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"]}'
{ "ok": true, "data": { "id": "[email protected]" } }
POST /groups/{group}/participants/add
Adicionar ao grupo. Categoria de limite: administração. Beta.
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"]}'
{ "ok": true, "data": { "results": [ { "participant": "5547999999999", "ok": true, "message": "" } ] } }
POST /groups/{group}/participants/remove
Tirar do grupo. Categoria de limite: administração. Beta.
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"]}'
{ "ok": true, "data": { "results": [ { "participant": "5547999999999", "ok": true, "message": "" } ] } }
POST /groups/{group}/participants/promote
Tornar administrador. Categoria de limite: administração. Beta.
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"]}'
{ "ok": true, "data": { "results": [ { "participant": "5547999999999", "ok": true, "message": "" } ] } }
POST /groups/{group}/participants/demote
Tirar de administrador. Categoria de limite: administração. Beta.
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"]}'
{ "ok": true, "data": { "results": [ { "participant": "5547999999999", "ok": true, "message": "" } ] } }
PUT /groups/{group}/name
Mudar o nome do grupo. Categoria de limite: administração. Beta.
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"}'
{ "ok": true, "data": {} }
PUT /groups/{group}/topic
Mudar a descrição do grupo. Categoria de limite: administração. Beta.
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"}'
{ "ok": true, "data": {} }
PUT /groups/{group}/photo
Mudar a foto do grupo. Categoria de limite: administração. Beta.
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"}}'
{ "ok": true, "data": {} }
PUT /groups/{group}/locked
Só admins editam o grupo. Categoria de limite: administração. Beta.
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}'
{ "ok": true, "data": {} }
PUT /groups/{group}/announce
Só admins enviam mensagens. Categoria de limite: administração. Beta.
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}'
{ "ok": true, "data": {} }
GET /groups/{group}/invite-link
Link de convite do grupo. Categoria de limite: leitura. Beta.
curl "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/invite-link?reset=false" \
-H "apikey: SUA_CHAVE"
{ "ok": true, "data": { "link": "https://chat.whatsapp.com/AbCdEfGh123" } }
POST /groups/join
Entrar num grupo por link. Categoria de limite: administração. Beta.
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"}'
{ "ok": true, "data": { "id": "[email protected]" } }
GET /groups/preview
Ver um grupo antes de entrar. Categoria de limite: leitura. Beta.
curl "https://proxybox.com.br/api/whatsapp/v1/groups/preview?link=https://chat.whatsapp.com/AbCdEfGh123" \
-H "apikey: SUA_CHAVE"
{ "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.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/leave" \
-H "apikey: SUA_CHAVE"
{ "ok": true, "data": {} }
GET /groups/{group}/requests
Pedidos para entrar no grupo. Categoria de limite: leitura. Beta.
curl "https://proxybox.com.br/api/whatsapp/v1/groups/[email protected]/requests" \
-H "apikey: SUA_CHAVE"
{ "ok": true, "data": { "requests": [] } }
POST /groups/{group}/requests/approve
Aprovar pedidos para entrar. Categoria de limite: administração. Beta.
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"]}'
{ "ok": true, "data": { "results": [ { "participant": "5511988887777", "ok": true, "message": "" } ] } }
POST /groups/{group}/requests/reject
Recusar pedidos para entrar. Categoria de limite: administração. Beta.
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"]}'
{ "ok": true, "data": { "results": [ { "participant": "5511988887777", "ok": true, "message": "" } ] } }
Canais
GET /channels
Listar canais. Categoria de limite: leitura. Beta.
curl "https://proxybox.com.br/api/whatsapp/v1/channels" \
-H "apikey: SUA_CHAVE"
{ "ok": true, "data": { "channels": [] } }
GET /channels/info
Dados de um canal. Categoria de limite: leitura. Beta.
curl "https://proxybox.com.br/api/whatsapp/v1/channels/info?newsletter_id=120363000000000000@newsletter" \
-H "apikey: SUA_CHAVE"
{ "ok": true, "data": { "id": "120363000000000000@newsletter", "name": "Novidades da loja" } }
POST /channels/follow
Seguir canal. Categoria de limite: ação. Beta.
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"}'
{ "ok": true, "data": {} }
POST /channels/unfollow
Deixar de seguir canal. Categoria de limite: ação. Beta.
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"}'
{ "ok": true, "data": {} }
GET /channels/messages
Mensagens de um canal. Categoria de limite: leitura. Beta.
curl "https://proxybox.com.br/api/whatsapp/v1/channels/messages?newsletter_id=120363000000000000@newsletter&count=20" \
-H "apikey: SUA_CHAVE"
{ "ok": true, "data": { "messages": [] } }
Agendamentos
GET /schedules
Listar mensagens agendadas. Categoria de limite: leitura. Beta.
curl "https://proxybox.com.br/api/whatsapp/v1/schedules?status=pending" \
-H "apikey: SUA_CHAVE"
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/schedules/17" \
-H "apikey: SUA_CHAVE"
{ "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.
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/schedules/17" \
-H "apikey: SUA_CHAVE"
{ "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.
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"}]}'
{ "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:
{ "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.
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}'
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/events?after=0&limit=50&wait=20" \
-H "apikey: SUA_CHAVE"
{ "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.
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}'
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/activity?status=failed&limit=20" \
-H "apikey: SUA_CHAVE"
{ "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.
curl "https://proxybox.com.br/api/whatsapp/v1/metrics?days=14" \
-H "apikey: SUA_CHAVE"
{ "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 |
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.
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 } }
DELETE /labels/{id}
Apagar a etiqueta e tirá-la de todas as conversas. Provado em aparelho real em 12/11/2026.
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.
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.
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"
{ "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.
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.
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.
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.
curl -X GET "https://proxybox.com.br/api/whatsapp/v1/approvals/12" \
-H "apikey: SUA_CHAVE"
{ "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.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/approvals/12/approve" \
-H "apikey: SUA_CHAVE"
{ "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.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/approvals/12/reject" \
-H "apikey: SUA_CHAVE"
{ "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.
curl -X GET "https://proxybox.com.br/api/whatsapp/v1/integrations" \
-H "apikey: SUA_CHAVE"
{ "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.
curl -X GET "https://proxybox.com.br/api/whatsapp/v1/integrations/bot" \
-H "apikey: SUA_CHAVE"
{ "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.
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}'
{ "ok": true, "data": { … } }
DELETE /integrations/bot
Apagar o bot e as sessões. Apaga o bot, as sessões e as chaves guardadas. Beta.
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/integrations/bot" \
-H "apikey: SUA_CHAVE"
{ "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.
curl -X GET "https://proxybox.com.br/api/whatsapp/v1/integrations/bot/sessions" \
-H "apikey: SUA_CHAVE"
{ "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.
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}'
{ "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.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/integrations/bot/sessions/5547999999999/reset" \
-H "apikey: SUA_CHAVE"
{ "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.
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?"}'
{ "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.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/integrations/chatwoot/rotate-token" \
-H "apikey: SUA_CHAVE"
{ "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.
curl -X GET "https://proxybox.com.br/api/whatsapp/v1/integrations/chatwoot" \
-H "apikey: SUA_CHAVE"
{ "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.
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}'
{ "ok": true, "data": { … } }
DELETE /integrations/{type}
Apagar uma integração. Remove a configuração e os segredos guardados. Beta.
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/integrations/chatwoot" \
-H "apikey: SUA_CHAVE"
{ "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.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/integrations/chatwoot/test" \
-H "apikey: SUA_CHAVE"
{ "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.
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/labels" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"name": "Cliente VIP"}'
{ "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.
curl -X DELETE "https://proxybox.com.br/api/whatsapp/v1/labels/12/chats" \
-H "apikey: SUA_CHAVE"
{ "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.
curl -X GET "https://proxybox.com.br/api/whatsapp/v1/labels/12/chats" \
-H "apikey: SUA_CHAVE"
{ "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.
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"}}'
{ "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.
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"}}'
{ "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. |
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/contacts/5547999999999/block' \
-H 'apikey: pbwa_SUA_CHAVE'
Resposta:
{ "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. |
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/contacts/5547999999999/unblock' \
-H 'apikey: pbwa_SUA_CHAVE'
Resposta:
{ "ok": true, "data": { } }
Contatos bloqueados
GET /blocked-contacts: Lista os números bloqueados pela instância.
curl -X GET 'https://proxybox.com.br/api/whatsapp/v1/blocked-contacts' \
-H 'apikey: pbwa_SUA_CHAVE'
Resposta:
{ "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. |
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:
{ "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. |
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:
{ "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. |
curl -X DELETE 'https://proxybox.com.br/api/whatsapp/v1/chats/5547999999999' \
-H 'apikey: pbwa_SUA_CHAVE'
Resposta:
{ "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. |
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:
{ "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. |
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:
{ "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. |
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:
{ "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). |
curl -X GET 'https://proxybox.com.br/api/whatsapp/v1/communities/120363025246125000%40g.us/groups' \
-H 'apikey: pbwa_SUA_CHAVE'
Resposta:
{ "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). |
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:
{ "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). |
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:
{ "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. |
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:
{ "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. |
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:
{ "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). |
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:
{ "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. |
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:
{ "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. |
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:
{ "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. |
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:
{ "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. |
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:
{ "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. |
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:
{ "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. |
curl -X POST 'https://proxybox.com.br/api/whatsapp/v1/groups/120363025246125000%40g.us/member-label' \
-H 'apikey: pbwa_SUA_CHAVE'
Resposta:
{ "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. |
curl -X DELETE 'https://proxybox.com.br/api/whatsapp/v1/status/3EB0C767D82B1A3F0E12' \
-H 'apikey: pbwa_SUA_CHAVE'
Resposta:
{ "ok": true, "data": { } }
Vídeo redondo e avisos por SSE
- Vídeo redondo:
POST /messages/videoaceitaround: truee envia o vídeo como mensagem de vídeo (a bolinha), sem legenda. Use vídeo curto e quadrado. - Avisos por SSE:
GET /events/streamentrega os mesmos avisos deGET /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
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
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#
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
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
- SDKs, OpenAPI e Postman da API de WhatsApp
- Erros e limites da API de WhatsApp
- Webhook da API de WhatsApp: eventos e assinatura
- Enviar a 1ª mensagem pela API de WhatsApp
Í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.