Eventos de cota de mensagem

Eventos relacionados à cota de mensagens por número, medida contra o ciclo de faturamento atual da organização (cycle_start/cycle_end). Limites por plano: Gratuito 300, Lobo Solitário 1.800, Empresarial 50 mil e Personalizado 500 mil por número, por ciclo.

A cota de mensagens é por número, como a cota de contatos: cada número vinculado (main ou um alias extra) tem sua própria cota, e uma organização com N números tem N vezes a cota do plano. Estes eventos identificam o número afetado pelo number_alias do envelope (não em data). Apenas mensagens enviadas pelo Turbo Notify (origin: "tn") consomem a cota.

Para configurar a URL do webhook, validar a assinatura e entender o envelope, veja Webhook: configuração e envelope.

Eventos

Evento	Quando
message.quota.warning	Cruzou o limiar de 80, 90 ou 95% da cota de mensagens do número
message.quota.exceeded	Tentativa rejeitada por estouro (HTTP 429)

number_alias no envelope

Ambos os eventos carregam, logo abaixo de organization_id, o campo number_alias: o identificador do número do Turbo Notify cuja cota de mensagens foi atingida ("main" para o número principal ou o alias de um número extra). O data do evento carrega os campos de cota threshold_percent (só em warning), used, quota, cycle_start, cycle_end, resets_at, tier, channel, origin. O number_alias fica no envelope, nunca dentro de data.

used/quota são medidos contra o ciclo de faturamento avaliado da organização (cycle_start/cycle_end, ISO 8601 UTC); resets_at é igual a cycle_end.

threshold_percent é a porcentagem da cota atingida, em número inteiro: 80, 90 ou 95 (80 quer dizer 80%). A cota esgotada não chega como threshold_percent: 100: chega como o evento message.quota.exceeded, que não tem esse campo.

Entre os eventos de conta, number_alias é omitido em storage.* e em media.unavailable. Toda a família *.quota.* (contatos e mensagens) carrega esse campo.

Exemplo: message.quota.warning

{
  "id": "evt_...",
  "type": "message.quota.warning",
  "organization_id": "org_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "number_alias": "main",
  "number_id": "num_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "created_at": "2026-06-20T12:00:00Z",
  "data": {
    "threshold_percent": 80,
    "used": 240,
    "quota": 300,
    "cycle_start": "2026-06-01T00:00:00Z",
    "cycle_end": "2026-07-01T00:00:00Z",
    "resets_at": "2026-07-01T00:00:00Z",
    "tier": "FREE",
    "channel": "whatsapp",
    "origin": "tn"
  }
}

Exemplo: message.quota.exceeded

{
  "id": "evt_...",
  "type": "message.quota.exceeded",
  "organization_id": "org_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "number_alias": "main",
  "number_id": "num_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "created_at": "2026-06-20T12:00:00Z",
  "data": {
    "quota": 300,
    "used": 300,
    "cycle_start": "2026-06-01T00:00:00Z",
    "cycle_end": "2026-07-01T00:00:00Z",
    "resets_at": "2026-07-01T00:00:00Z",
    "tier": "FREE",
    "channel": "whatsapp",
    "origin": "tn"
  }
}

Timestamps e correlação

• Estes eventos são gerados pelo próprio Turbo Notify (não refletem uma ação no WhatsApp): não carregam at em data, apenas o created_at do envelope (momento de emissão do evento pelo Turbo Notify).
• cycle_start/cycle_end são o ciclo de faturamento avaliado contra o qual used/quota foram medidos. resets_at é o momento em que a contagem da cota recomeça: igual a cycle_end na emissão, não é o momento em que algo aconteceu.
• Não há phone no conteúdo destes eventos. Para correlacionar com a requisição que disparou o estouro, use GET /v1/events?request_id=req_....

Ação recomendada

• Mude para um plano maior (veja a tabela de planos em Cota e uso).
• Acompanhe no dashboard, em Uso, o consumo de cada número no ciclo atual.