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.
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ção | Escopo |
|---|---|---|
| Uso de um projeto frente ao plano | GET /tenants/{id}/usage | usage:read |
| Totais diários de todos os seus projetos | GET /usage/daily | usage:read |
| Registro de mensagens | GET /messages | logs:read |
| Registro de entregas de webhook | GET /webhooks/deliveries | logs:read |
| Reenviar uma entrega | POST /webhooks/deliveries/{id}/resend | webhooks:write |
| Reenviar todas as entregas mortas | POST /webhooks/deliveries/resend-dead | webhooks: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"const res = await fetch(`https://api.apiwpp.com/tenants/${process.env.TENANT_ID}/usage?days=7`, {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
})
const { plan, organization } = await res.json()
if (plan && plan.maxMessagesMonth > 0 && organization.usage.percentOfMonthlyLimit >= 80) {
console.warn(`A organização já usou ${organization.usage.percentOfMonthlyLimit.toFixed(1)}% da cota do mês`)
}{
"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 }
]
}| Campo | O que traz |
|---|---|
plan | O 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. |
usage | As mensagens enviadas pelo próprio projeto hoje e no mês, e quanto elas representam das cotas da organização, em porcentagem. |
organization.usage | As mesmas contas somando todos os projetos da organização. É sobre esse número que as cotas valem. |
subscription | O status da assinatura, o fim do período de teste (trialEndsAt) e o fim do período pago (currentPeriodEnd). |
dailyUsage | Uma 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çalhoX-Usage-Percente umerrorque diz qual cota passou, por exemploDaily 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).
curl -s "https://api.apiwpp.com/usage/daily?days=2" \
-H "Authorization: Bearer $API_KEY"{ "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âmetro | Descrição |
|---|---|
direction | out (enviadas) ou in (recebidas). |
status | queued, sent, delivered, read, failed ou received. |
tenantId | Só as mensagens de um projeto. |
connectionId | Só as mensagens de uma conexão. |
q | Busca, 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. |
limit | Quantas 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"const params = new URLSearchParams({ status: 'failed', connectionId, limit: '200' })
const res = await fetch(`https://api.apiwpp.com/messages?${params}`, {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
})
const { messages, counts } = await res.json()
for (const m of messages) console.log(m.contact, m.clientRef, m.error){
"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),locationoutemplate; nas recebidas, é o tipo de mensagem que chegou. Obodyé 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
queuede só avança:sent,delivered,read. Confirmações fora de ordem não fazem o status voltar.failedvale a qualquer momento, com o motivo emerror; uma recebida fica emreceived.eventsguarda cada mudança com o horário. countsaplica todos os filtros menosdirection, 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:
state | O que quer dizer |
|---|---|
delivered | O seu endpoint respondeu 2xx. |
retry | A entrega falhou e está aguardando uma nova tentativa em nextAttemptAt. |
dead | As 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": …}.
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}/resendreenvia uma entrega emdeadou emretrye responde a linha atualizada. Uma entrega já feita responde409, e uma cujo payload não foi guardado (maior que 256 KB) também.POST /webhooks/deliveries/resend-deadreenvia de uma vez as entregasdeadde 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 continuamdead, com o erropayload not available for resend. Se havia mais de 1000, chame de novo, enquantorequeuedvier igual a 1000. Mas as que ficaramdeadsem corpo guardado voltam a ocupar as 1000 vagas da próxima chamada, que começa sempre pelas mais novas: serequeuedvier abaixo de 1000 e ainda houver entregasdeadmais antigas, reenvie essas uma a uma comPOST /webhooks/deliveries/{id}/resend.
curl -s -X POST https://api.apiwpp.com/webhooks/deliveries/resend-dead \
-H "Authorization: Bearer $API_KEY"let requeued
do {
const res = await fetch('https://api.apiwpp.com/webhooks/deliveries/resend-dead', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
})
;({ requeued } = await res.json())
} while (requeued === 1000){ "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
| Dado | Retenção padrão |
|---|---|
Registro de mensagens (GET /messages) | 7 dias |
Registro de entregas de webhook (GET /webhooks/deliveries), com os payloads | 7 dias |
| Eventos de conexão, de onde vem o histórico de heartbeats | 30 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
- Uso do projeto e Listar mensagens: todos os campos e respostas.
- Webhooks e assinatura: receber, verificar e responder os eventos.
- Limites de envio: o ritmo por número, o aquecimento e os outros
429. - Idempotência: o
clientRefque liga o envio ao registro e aos eventos.