Recurso em beta: pode mudar. Os papéis foram testados em ambiente de teste. A gestão da equipe é feita no painel; esta versão não oferece rotas de API para convidar ou remover pessoas.
Para que serve?
Para atendimento em time. Em vez de passar a chave de uma pessoa para outra (e depois não saber quem enviou o quê), cada atendente entra com a própria conta da ProxyBox e usa o painel da instância. Quando alguém sai da equipe, o dono remove o acesso daquela pessoa, sem trocar a chave nem mexer nas integrações.
O que cada papel pode fazer?
| Área | Dono | Operador | Visualizador |
|---|---|---|---|
| Ver estado da instância e do número | sim | sim | sim |
| Ver conversas e mensagens | sim | sim | sim |
| Ver atividade e métricas | sim | sim | sim |
| Enviar mensagens pelo painel | sim | sim | não |
| Responder conversas e agir sobre mensagens | sim | sim | não |
| Contatos, grupos, agendadas | sim | sim | não |
| Etiquetas | sim | sim | não |
| Chave da API, trocar chave | sim | não | não |
| Avisos automáticos e integrações | sim | não | não |
| Ajustes, IPs permitidos, recusar chamadas | sim | não | não |
| Desconectar o número, cancelar a instância | sim | não | não |
A regra vive num único verificador no servidor, e o painel passa por ele. Se uma ação não está permitida ao papel, o botão nem aparece, e a ação é recusada no servidor.
Como convido alguém?
- No painel, abra a instância e a aba da equipe.
- Digite o e-mail da conta da ProxyBox da pessoa e escolha o papel.
- A pessoa recebe um aviso do convite e a instância passa a aparecer na lista dela, com o selo Visualizador ou Operador.
Para mudar o papel, o dono escolhe outro na lista. Para tirar a pessoa, remove-a. A própria pessoa também pode sair da instância.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisE a equipe da ProxyBox?
O pessoal de suporte da ProxyBox não entra na instância por padrão. Só a administração da ProxyBox, para fins de operação do serviço, tem acesso amplo, e mesmo assim sem acesso à chave. Detalhes do que guardamos e de quem vê o quê estão em segurança.
Por que a chave não é compartilhada?
Porque a chave é o acesso programático à instância: com ela, qualquer sistema envia mensagens em nome do número, sem papel nem registro de quem. Os papéis existem justamente para evitar isso. Quem precisa programar contra a API deve receber a chave do dono, que pode restringi-la a IPs permitidos, e o uso fica no registro de atividade com o campo via.
Como isso aparece na atividade?
Mensagens enviadas por pessoas no painel entram no registro com via igual a panel; as enviadas por código, api; por um bot, bot; pelo assistente de IA, mcp. Assim o dono separa o trabalho do time do trabalho dos sistemas. Por política de privacidade, o registro guarda só os quatro últimos dígitos do destino e não guarda o texto.
Dicas de uso
- Comece com visualizador para supervisores e quem só acompanha. Dê operador só a quem de fato vai responder clientes.
- Combine com a aprovação humana. Com a aprovação em modo
bots, um assistente de IA propõe a resposta e uma pessoa da equipe a libera. - Revise a lista quando alguém mudar de função. Remover o acesso é imediato.
- Um número, vários atendentes, mesmo ritmo. O limite de mensagens continua sendo da instância, não de cada pessoa: dois operadores enviando ao mesmo tempo dividem o mesmo teto de 10 por minuto.
O que a equipe não resolve?
- Não há transferência de conversa entre atendentes nem fila de atendimento: isso é papel de uma ferramenta de atendimento. Para isso, ligue a instância ao Chatwoot, que tem atribuição de agentes, e deixe a equipe lá.
- Não há limite de envio individual por pessoa.
- Não há papéis personalizados além dos dois.
Os termos usados aqui estão no glossário.
Como vejo a atividade e as métricas?
Resposta curta: GET /activity devolve as últimas operações da instância (uma linha por operação, guardadas por 30 dias, sem o texto das mensagens) e GET /metrics?days=14 devolve o resumo por dia: envios que deram certo e que falharam, os erros e as operações mais frequentes, o tempo médio e a porcentagem de avisos entregues ao seu endereço. As mesmas informações aparecem na aba Atividade do painel.
Recurso em beta: pode mudar. Os nomes dos campos podem ganhar acréscimos; programe o seu código para ignorar o que não conhece.
Para que serve? (atividade)
Para responder, sem abrir ticket, três perguntas que aparecem em toda operação:
- "Por que a mensagem não saiu?" A linha da operação mostra o código HTTP e o erro (
rate_limited,new_contacts_locked,not_connected...). - "Estou perto do limite?" O resumo por dia mostra quantos envios foram feitos e quantos falharam.
- "O meu sistema está recebendo os avisos?" O bloco
webhooksmostra quantos foram entregues, desistidos e quantos esperam.
Como vejo as últimas operações?
curl "https://proxybox.com.br/api/whatsapp/v1/activity?limit=50" \
-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
}
}
| Campo | Significado |
|---|---|
op |
A operação, como send.text ou group.add |
cat |
A categoria de limite (send, act, read, lookup, admin, status) |
via |
Quem pediu: api, panel, bot, mcp, scheduler, approval ou zapi |
http e error |
O resultado, no mesmo padrão dos erros da API |
ms |
Quanto tempo a operação levou |
to_tail4 |
Só os 4 últimos dígitos do destino |
Filtros: limit (1 a 200, padrão 50), op (por exemplo send.text), status (ok, failed ou um código como 429) e before (o next_before da resposta anterior, para paginar para trás).
# só as falhas de envio de texto
curl "https://proxybox.com.br/api/whatsapp/v1/activity?op=send.text&status=failed" -H "apikey: SUA_CHAVE"
Como vejo o resumo?
curl "https://proxybox.com.br/api/whatsapp/v1/metrics?days=14" \
-H "apikey: SUA_CHAVE"
{
"ok": true,
"data": {
"days": [
{ "date": "2026-11-11", "sent": 212, "failed": 7 },
{ "date": "2026-11-12", "sent": 188, "failed": 3 }
],
"by_op": { "send.text": 351, "send.image": 40, "contact.check": 12 },
"by_error": { "rate_limited": 6, "number_not_on_whatsapp": 4 },
"avg_ms": 640,
"delivered_pct": 99.1,
"webhooks": { "ok": 402, "dead": 3, "pending": 0 }
}
}
daysvai de 1 a 30 (padrão 14).sentefailedcontam envios (send.*estatus.*) com HTTP abaixo de 400 e de 400 para cima, por dia, no horário de Brasília.by_opeby_errorsomam o período inteiro.avg_msé o tempo médio das operações registradas.delivered_pcté a parte dos avisos ao seu endereço que chegaram: entregues divididos por entregues mais desistidos. Se ficar baixo, o seu receptor está recusando ou demorando; veja o aviso automático.webhooksconta avisos entregues (ok), desistidos (dead) e na fila (pending).
O que nunca aparece?
O registro foi desenhado para ser seguro de consultar e de mostrar à equipe:
- o texto das mensagens nunca é guardado;
- o telefone aparece só com os 4 últimos dígitos;
- chaves, segredos e endereços de integração nunca entram;
- as consultas
activity.list,metrics.get,events.listeevents.acknão são registradas.
Registros com mais de 30 dias são apagados automaticamente.
Como uso em código?
Um alarme simples em Python, para avisar quando mais de 10% dos envios do dia falham:
import os, requests
r = requests.get("https://proxybox.com.br/api/whatsapp/v1/metrics",
headers={"apikey": os.environ["WA_KEY"]}, params={"days": 1}, timeout=30)
dia = r.json()["data"]["days"][-1]
total = dia["sent"] + dia["failed"]
if total >= 20 and dia["failed"] / total > 0.10:
print("Atenção: falhas altas hoje", dia)
Em Node, o mesmo com fetch:
const r = await fetch("https://proxybox.com.br/api/whatsapp/v1/activity?status=failed&limit=20", { headers: { apikey: process.env.WA_KEY } });
const { data } = await r.json();
for (const i of data.items) console.log(i.created_at, i.op, i.http, i.error);
Quem vê a atividade?
No painel, a aba Atividade mostra um gráfico dos últimos 14 dias, as últimas 200 operações e os filtros. Quem tem o papel de visualizador na equipe da instância pode ver; a chave e os ajustes continuam só com o dono.
Como a atividade ajuda a achar a causa de uma falha?
Comece por GET /activity?status=failed e olhe o campo error das linhas mais recentes. rate_limited e daily_limit dizem que o ritmo está acima do permitido; not_connected mostra que o número caiu; new_contacts_locked indica a trava de contato novo; number_not_on_whatsapp aponta lista com telefones errados. Se as falhas se concentram numa operação (by_op em GET /metrics), o problema costuma estar no seu código; se aparecem em todas, olhe o estado da instância e o aviso connection.updated.
Limites e cuidados
- O registro serve para diagnóstico e para ver tendência, não como prova de entrega: o WhatsApp é quem confirma o recebimento, e isso chega pelos avisos
message.status. - A atividade mostra o que a API fez. Mensagens que você enviou direto pelo celular não entram, a não ser como aviso
message.sent. - Se uma operação deu timeout (504), o registro mostra o 504; a mensagem pode ter saído. Confira antes de reenviar e use
Idempotency-Key.
Veja também
- Segurança da API de WhatsApp: chave e IPs
- Chatwoot com WhatsApp: ligar pela API
- Aprovação humana de mensagens da API de WhatsApp
- Webhook da API de WhatsApp: eventos e assinatura
Índice completo: documentação. Sobre o produto: a oferta de API de WhatsApp da ProxyBox.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026, contra a tabela de membros e os papéis da versão 1.2. Recurso em beta; gestão pelo painel.