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

Como dar acesso à equipe e acompanhar a atividade da instância?

Convide pessoas sem dar a chave (visualizador e operador) e acompanhe o registro de atividade e as métricas com GET /activity e GET /metrics. Beta.

10 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
O dono da instância convida outras contas da ProxyBox pelo e-mail e escolhe um papel: visualizador (ver o estado, as conversas e a atividade) ou operador (tudo isso, mais enviar mensagens e mexer em contatos, grupos, agendadas e etiquetas). Nenhum dos dois vê a chave, os avisos, os ajustes, os IPs permitidos nem as integrações, e nenhum pode desconectar ou cancelar. A instância aparece na lista do convidado com um selo do papel. A segunda metade do guia mostra a atividade e as métricas da instância (GET /activity e GET /metrics, 30 dias, sem o texto das mensagens).

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?

  1. No painel, abra a instância e a aba da equipe.
  2. Digite o e-mail da conta da ProxyBox da pessoa e escolha o papel.
  3. 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átis

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

  1. "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...).
  2. "Estou perto do limite?" O resumo por dia mostra quantos envios foram feitos e quantos falharam.
  3. "O meu sistema está recebendo os avisos?" O bloco webhooks mostra quantos foram entregues, desistidos e quantos esperam.

Como vejo as últimas operações?

bash
curl "https://proxybox.com.br/api/whatsapp/v1/activity?limit=50" \
  -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
  }
}
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).

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

bash
curl "https://proxybox.com.br/api/whatsapp/v1/metrics?days=14" \
  -H "apikey: SUA_CHAVE"
json
{
  "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 }
  }
}
  • days vai de 1 a 30 (padrão 14). sent e failed contam envios (send.* e status.*) com HTTP abaixo de 400 e de 400 para cima, por dia, no horário de Brasília.
  • by_op e by_error somam 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.
  • webhooks conta 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.list e events.ack nã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:

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

js
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

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

Perguntas frequentes

A pessoa convidada precisa ter conta na ProxyBox?
Sim. O dono adiciona pelo e-mail de uma conta que já existe. Quem não tem conta cria uma antes.
O convidado vê a chave da API?
Nunca. A chave, os avisos automáticos, os ajustes, os IPs permitidos e as integrações são só do dono.
Um convidado pode desconectar o número?
Não. Desconectar, cancelar a instância e trocar a chave são ações do dono.
A atividade guarda o texto das mensagens que enviei?
Não. Guarda a operação, a categoria, o canal de origem, o código HTTP, o erro, o tempo gasto e os quatro últimos dígitos do destino. Nunca o conteúdo.
Por quanto tempo o registro fica?
Trinta dias.
As consultas de atividade aparecem na própria atividade?
Não. activity.list, metrics.get, events.list e events.ack não são registradas, para a consulta não encher o registro.

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