Pular para o conteúdo

Uso e registros

Quanto os seus projetos enviaram frente ao plano, o registro de mensagens e de entregas de webhook, o reenvio de webhooks e por quanto tempo tudo fica guardado.

Ver em Markdown

A apiwpp conta as mensagens de cada projeto e guarda um registro das mensagens e das entregas de webhook. É o mesmo registro que o painel mostra, e a API o expõe para você montar os seus próprios relatórios e alertas. Cada operação vale para os projetos que a chave alcança: pedir um tenantId de fora deles responde 404, como se não existisse.

O quêOperaçãoEscopo
Uso de um projeto frente ao planoGET /tenants/{id}/usageusage:read
Totais diários de todos os seus projetosGET /usage/dailyusage:read
Registro de mensagensGET /messageslogs:read
Registro de entregas de webhookGET /webhooks/deliverieslogs:read
Reenviar uma entregaPOST /webhooks/deliveries/{id}/resendwebhooks:write
Reenviar todas as entregas mortasPOST /webhooks/deliveries/resend-deadwebhooks:write

Uso do projeto

GET /tenants/{id}/usage traz as mensagens enviadas hoje e neste mês pelo projeto e pela organização dele, o plano, a assinatura e o histórico diário do projeto. Os dias e os meses são contados em UTC. O parâmetro days escolhe o tamanho do histórico: padrão 30, no máximo 366.

curl -s "https://api.apiwpp.com/tenants/$TENANT_ID/usage?days=7" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "plan": { "name": "pro", "displayName": "Pro", "maxMessagesDay": 1000, "maxMessagesMonth": 20000 },
  "usage": { "today": 12, "thisMonth": 540, "percentOfDailyLimit": 1.2, "percentOfMonthlyLimit": 2.7 },
  "organization": {
    "id": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
    "usage": { "today": 30, "thisMonth": 1200, "percentOfDailyLimit": 3, "percentOfMonthlyLimit": 6 }
  },
  "subscription": { "status": "active", "trialEndsAt": null, "currentPeriodEnd": "2026-10-24T12:00:00.000Z" },
  "dailyUsage": [
    { "date": "2026-09-23", "messagesSent": 42, "messagesRecv": 17 },
    { "date": "2026-09-24", "messagesSent": 12, "messagesRecv": 5 }
  ]
}
CampoO que traz
planO plano da organização: maxMessagesDay e maxMessagesMonth são as cotas de mensagens (-1: sem cota). null quando a organização não tem plano, o que também quer dizer sem cota.
usageAs mensagens enviadas pelo próprio projeto hoje e no mês, e quanto elas representam das cotas da organização, em porcentagem.
organization.usageAs mesmas contas somando todos os projetos da organização. É sobre esse número que as cotas valem.
subscriptionO status da assinatura, o fim do período de teste (trialEndsAt) e o fim do período pago (currentPeriodEnd).
dailyUsageUma linha por dia do projeto, com as mensagens enviadas (messagesSent) e recebidas (messagesRecv).

Uma mensagem conta como enviada quando sai da fila para o WhatsApp, não quando a API a aceita.

A cota do plano no envio

Os planos são da organização, e todos os projetos dela somam para as cotas diária e mensal. Os planos por número, LITE e PRO, não têm cota de mensagens (-1): neles os percentuais ficam em 0, e os únicos limites de envio são os de ritmo que protegem o número (veja Limites de envio).

Num plano com cota, cada POST /connections/{id}/send confere o uso da organização somado às mensagens que já estão na fila e ainda não saíram:

  • a partir de 80% da cota, o envio é aceito com o cabeçalho X-Usage-Warning: Approaching limit: 85% used;
  • a partir de 110% da cota (uma margem de 10% para requisições simultâneas), o envio é recusado com 429, o cabeçalho X-Usage-Percent e um error que diz qual cota passou, por exemplo Daily message limit exceeded (1100/1000). A cota mensal é conferida antes da diária.

Esse 429 não traz Retry-After: a cota diária volta à meia-noite UTC e a mensal no primeiro dia do mês. A página Erros mostra como separar esse 429 dos outros.

Uso diário

GET /usage/daily soma, dia a dia, as mensagens enviadas e recebidas de todos os projetos que a chave alcança. Vem uma entrada por dia em UTC, incluindo os dias zerados, do mais antigo ao mais recente; hoje é a última. O parâmetro days vai de 1 a 90 (padrão 14).

bashVer na referência
curl -s "https://api.apiwpp.com/usage/daily?days=2" \
  -H "Authorization: Bearer $API_KEY"
200
{ "days": [ { "date": "2026-09-23", "sent": 42, "received": 17 }, { "date": "2026-09-24", "sent": 12, "received": 5 } ] }

Registro de mensagens

GET /messages lista as mensagens enviadas pela API e as recebidas, das mais novas para as mais antigas. As mensagens que você manda direto do celular não entram no registro.

ParâmetroDescrição
directionout (enviadas) ou in (recebidas).
statusqueued, sent, delivered, read, failed ou received.
tenantIdSó as mensagens de um projeto.
connectionIdSó as mensagens de uma conexão.
qBusca, sem diferenciar maiúsculas, no contato, no texto, no jobId, no clientRef e no messageId. Um telefone formatado, como +55 (11) 98888-7777, também encontra o contato gravado só com dígitos.
limitQuantas linhas trazer: padrão 60, no máximo 200.
curl -s -G https://api.apiwpp.com/messages \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "q=pedido-1234" \
  --data-urlencode "limit=20"
200
{
  "messages": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
      "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
      "direction": "out",
      "contact": "5511988887777",
      "type": "text",
      "body": "Olá! Sua consulta está confirmada.",
      "status": "delivered",
      "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
      "clientRef": "pedido-1234",
      "messageId": "3EB0C767D26A1D8A3F52",
      "error": null,
      "events": [
        { "status": "queued", "at": "2026-09-24T11:59:55.000Z" },
        { "status": "sent", "at": "2026-09-24T12:00:00.000Z" },
        { "status": "delivered", "at": "2026-09-24T12:00:02.000Z" }
      ],
      "createdAt": "2026-09-24T11:59:55.000Z",
      "updatedAt": "2026-09-24T12:00:02.000Z"
    }
  ],
  "counts": { "all": 1, "in": 0, "out": 1 }
}

Como ler cada linha:

  • contact é o telefone do contato, ou a parte do JID antes do @ quando o endereço não é um telefone (um LID ainda não resolvido ou um grupo).
  • Nas enviadas, type é text, o tipo da mídia (image, audio, video, document, sticker), location ou template; nas recebidas, é o tipo de mensagem que chegou. O body é uma prévia de até 1000 caracteres: o texto, a legenda, o nome do arquivo ou o nome do local.
  • Uma mensagem enviada começa em queued e só avança: sent, delivered, read. Confirmações fora de ordem não fazem o status voltar. failed vale a qualquer momento, com o motivo em error; uma recebida fica em received. events guarda cada mudança com o horário.
  • counts aplica todos os filtros menos direction, para você saber quantas há em cada direção de uma vez.

Registro de entregas de webhook

GET /webhooks/deliveries traz uma linha por evento de webhook, das mais novas para as mais antigas, com o estado da entrega:

stateO que quer dizer
deliveredO seu endpoint respondeu 2xx.
retryA entrega falhou e está aguardando uma nova tentativa em nextAttemptAt.
deadAs tentativas acabaram sem sucesso. A entrega só sai daqui por um reenvio.

Os filtros são state, tenantId e limit (padrão 60, no máximo 200). Cada linha traz o eventType, a url chamada, o httpStatus e o error da última tentativa, a latência em latencyMs, as tentativas feitas (attempts) e o máximo (maxAttempts, hoje 6), se a entrega foi assinada (signed) e o payload enviado. Um payload maior que 256 KB não é guardado: no lugar dele vem {"_truncated": true, "type": "…", "bytes": …}.

bashVer na referência
curl -s "https://api.apiwpp.com/webhooks/deliveries?state=dead&limit=50" \
  -H "Authorization: Bearer $API_KEY"

counts traz o total por estado ignorando o filtro state, e stats resume todas as linhas guardadas: successRate de 0 a 100 (null sem nenhuma linha) e avgLatencyMs, a latência média das entregas bem-sucedidas. O guia Webhooks e assinatura explica o prazo de resposta e o calendário das novas tentativas.

Reenviar

Depois de corrigir o seu endpoint, reenvie o que ficou para trás. O reenvio põe a entrega na fila para agora, com um limite de tentativas novo.

  • POST /webhooks/deliveries/{id}/resend reenvia uma entrega em dead ou em retry e responde a linha atualizada. Uma entrega já feita responde 409, e uma cujo payload não foi guardado (maior que 256 KB) também.
  • POST /webhooks/deliveries/resend-dead reenvia de uma vez as entregas dead de todos os projetos que a chave alcança, até 1000 por chamada, das mais novas para as mais antigas, e responde quantas voltaram para a fila. As que não têm payload guardado continuam dead, com o erro payload not available for resend. Se havia mais de 1000, chame de novo, enquanto requeued vier igual a 1000. Mas as que ficaram dead sem corpo guardado voltam a ocupar as 1000 vagas da próxima chamada, que começa sempre pelas mais novas: se requeued vier abaixo de 1000 e ainda houver entregas dead mais antigas, reenvie essas uma a uma com POST /webhooks/deliveries/{id}/resend.
curl -s -X POST https://api.apiwpp.com/webhooks/deliveries/resend-dead \
  -H "Authorization: Bearer $API_KEY"
200
{ "requeued": 3 }

Um evento reenviado chega de novo ao seu endpoint com o mesmo conteúdo. Como a entrega já é pelo menos uma vez, trate eventos repetidos sem efeito duplicado.

Por quanto tempo fica guardado

DadoRetenção padrão
Registro de mensagens (GET /messages)7 dias
Registro de entregas de webhook (GET /webhooks/deliveries), com os payloads7 dias
Eventos de conexão, de onde vem o histórico de heartbeats30 dias

A limpeza roda a cada 6 horas, então uma linha pode durar algumas horas além do prazo. Uma entrega que passou do prazo não pode mais ser reenviada. Os totais de uso (GET /tenants/{id}/usage e GET /usage/daily) não entram nessa limpeza. Se você precisa de um histórico mais longo das mensagens, guarde os eventos de webhook no seu sistema.

Próximos passos

Esta página ajudou? · Atualizado em 29 set 2026