Consumo e limiti

GET /v1/usage

GET /v1/usage restituisce il consumo del periodo: used, included, remaining, policy (block|queue) e un breakdown per origine (api, contact, device). ⚠ Regola del traffico del telefono (Coexistence): used = api + contact; il traffico device (quello che il titolare manda dal cellulare) viene mostrato ma NON consuma il piano. Il limite PER NUMERO (monthlyMessageLimit) conta solo api. Per numero: /v1/connections/:id/usage e /v1/usage/by-connection; sovrallocazione 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

⚠ Quattro limiti diversi, che non si mescolano. (1) Quello del piano: i piani pubblici non hanno un tetto di messaggi, quindi included e remaining arrivano a null e policy non ha niente su cui agire; solo un piano su misura con una quota concordata restituisce numeri interi (e lì QUOTA_EXCEEDED). used misura tutto comunque. (2) Il tuo, per numero: monthlyMessageLimit, che imposti tu con PATCH /v1/connections/:id; conta solo api e, quando si esaurisce, dà CONNECTION_QUOTA_EXCEEDED. (3) La velocità dell'API: 600 richieste al minuto per key; se la superi ottieni RATE_LIMITED (429, con Retry-After). (4) Quelli di Meta, nel punto seguente.

I bucket si aggregano in UTC; il timezone dell'account viene restituito solo perché tu possa comporre la didascalia.

⚠⚠ I LIMITI DI META SONO UN'ALTRA COSA, E SONO QUELLI CHE TI FERMERANNO. Noi non ti mettiamo un tetto di messaggi; Meta sì, te ne mette due, e non si mescolano. (1) CONTATTI — con quante persone DIVERSE avvii una conversazione in 24 h: 250 → 2.000 → 10.000 → 100.000 → senza limite, e si sale con la verifica dell'attività, il volume e la qualità. ⚠ Dal 7 ottobre 2025 quel limite è per PORTAFOGLIO aziendale, non per numero: tutti i numeri dello stesso portafoglio CONDIVIDONO la quota. Se gestisci numeri di più clienti, dimensiona tenendone conto. (2) RITMO — quanto velocemente partono: fino a 80 messaggi/secondo per numero sulla Cloud API (fino a 1.000 con l'aumento automatico), e 20/secondo fissi per un numero in Coexistence; se li superi ricevi il 130429 di Meta. Da parte nostra non perdi messaggi andando più veloce: la coda li assorbe e li smaltisce, con nuovi tentativi e idempotenza. Verificato sulla documentazione di Meta il 30/08/2026.

Le soglie del 70/90/100% arrivano via webhook (usage.threshold_reached / connection.usage_threshold_reached). ⚠ Quella di ACCOUNT è relativa alla quota del piano, quindi senza tetto non scatta; quella PER NUMERO (connection.usage_threshold_reached) sì, perché quel limite lo imposti tu.

Quello che addebita Meta è a parte rispetto a tutto questo: vedi Cosa addebita Meta e cosa addebita WAIA Connect.