Uso e limites

GET /v1/usage

GET /v1/usage dá o consumo do período: used, included, remaining, policy (block|queue) e um breakdown por origem (api, contact, device). ⚠ Regra do tráfego do celular (Coexistence): used = api + contact; o tráfego device (o que o dono manda pelo celular) é mostrado mas NÃO consome o plano. O limite POR NÚMERO (monthlyMessageLimit) conta só api. Por número: /v1/connections/:id/usage e /v1/usage/by-connection; sobrevenda informativa: /v1/accounts/oversubscription.

curl https://api.waiaconnect.com/v1/usage \
  -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# Public plan (no message cap): included and remaining are null.
# → { "used": 89, "included": null, "remaining": null, "policy": "block",
#     "breakdown": { "api": 0, "contact": 89, "device": 62 },
#     "breakdownNote": "used = api + contact; device does not count" }
# Only a custom plan with an agreed quota returns integers: "included": 25000, "remaining": 24911

const res = await fetch("https://api.waiaconnect.com/v1/usage", {
  headers: { "Authorization": "Bearer wc_live_YOUR_API_KEY" }
});
const u = await res.json();
// Public plans have no message cap: included/remaining are null (a custom plan returns integers).
console.log(u.used, "/", u.included ?? "no cap"); // device is in u.breakdown.device but NOT billed

<?php
$ch = curl_init("https://api.waiaconnect.com/v1/usage");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer wc_live_YOUR_API_KEY"],
]);
$u = json_decode(curl_exec($ch), true);
// Public plans have no message cap: included/remaining are null (a custom plan returns integers).
echo $u["used"] . " / " . ($u["included"] ?? "no cap"); // device is shown but not billed

import requests
res = requests.get("https://api.waiaconnect.com/v1/usage",
  headers={"Authorization": "Bearer wc_live_YOUR_API_KEY"})
u = res.json()
# Public plans have no message cap: included/remaining are None (a custom plan returns integers).
print(u["used"], "/", u["included"] if u["included"] is not None else "no cap")  # device is shown but not billed

⚠ Quatro limites diferentes, que não se misturam. (1) O do plano: os planos públicos não têm teto de mensagens, então included e remaining chegam em null e policy não tem sobre o que agir; só um plano sob medida com cota pactuada devolve inteiros (e aí QUOTA_EXCEEDED). used mede tudo igual. (2) O seu, por número: monthlyMessageLimit, que você define com PATCH /v1/connections/:id; conta só api e, ao esgotar, dá CONNECTION_QUOTA_EXCEEDED. (3) A velocidade da API: 600 pedidos por minuto por chave; passar disso dá RATE_LIMITED (429, com Retry-After). (4) Os da Meta, no ponto seguinte.

Os buckets são agregados em UTC; o timezone da conta é devolvido só para você montar a legenda.

⚠⚠ OS LIMITES DA META SÃO OUTRA COISA, E SÃO ELES QUE VÃO TE FREAR. Nós não pomos teto de mensagens; a Meta põe dois, e eles não se misturam. (1) CONTATOS — com quantas pessoas DIFERENTES você inicia conversa em 24 h: 250 → 2.000 → 10.000 → 100.000 → sem limite, e sobe com verificação do negócio, volume e qualidade. ⚠ Desde 7 de outubro de 2025 esse limite é por PORTFÓLIO empresarial, não por número: todos os números do mesmo portfólio COMPARTILHAM a cota. Se você administra números de vários clientes, dimensione com isso em mente. (2) RITMO — com que velocidade saem: até 80 mensagens/segundo por número na Cloud API (até 1.000 com o upgrade automático), e 20/segundo fixo para um número em Coexistence; passar disso devolve o 130429 da Meta. Do nosso lado você não perde mensagens por ir mais rápido: a fila as absorve e as drena, com novas tentativas e idempotência. Verificado contra a documentação da Meta em 30/08/2026.

Os limiares de 70/90/100% chegam por webhook (usage.threshold_reached / connection.usage_threshold_reached). ⚠ O de CONTA é relativo à cota do plano, então sem teto ele não dispara; o POR NÚMERO (connection.usage_threshold_reached) sim, porque esse limite é você quem define.

O que a Meta cobra é à parte de tudo isto: veja O que a Meta cobra e o que o WAIA Connect cobra.