Uso y límites

GET /v1/usage

¿Programás con IA? Conectala a tu cuenta por MCP: revisa tu configuración, crea webhooks y plantillas con tu confirmación y te escribe el código. Ver cómo →

GET /v1/usage da el consumo del período: used, included, remaining, policy (block|queue) y un breakdown por origen (api, contact, device). ⚠ Regla del tráfico del teléfono (Coexistence): used = api + contact; el tráfico device (lo que el dueño manda desde el celular) se muestra pero NO consume el plan. El límite POR NÚMERO (monthlyMessageLimit) cuenta solo api. Por número: /v1/connections/:id/usage y /v1/usage/by-connection; sobreventa informativa: /v1/accounts/oversubscription. Números del plan: includedNumbers, activeNumbers (registrados ahora), extraNumbersThisCycle (números extra del ciclo en números/mes, prorrateado por días, con decimales), extraEstimateUsd y nextChargeEstimate (date, baseUsd, extraUsd, totalUsd). Escala incluye 30 números y suma US$ 3 por número extra por mes, prorrateado por días, que se cobra con el abono siguiente; con menos de 30 el abono sigue en US$ 99.

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

⚠ Cuatro límites distintos, que no se mezclan. (1) El del plan: los planes públicos no tienen tope de mensajes, así que included y remaining llegan en null y policy no tiene sobre qué actuar; sólo un plan a medida con cupo pactado devuelve enteros (y ahí QUOTA_EXCEEDED). used mide todo igual. (2) El tuyo, por número: monthlyMessageLimit, que ponés vos con PATCH /v1/connections/:id; cuenta sólo api y al agotarse da CONNECTION_QUOTA_EXCEEDED. (3) La velocidad de la API: el envío, por número (Convivencia 20/s, Cloud API 80/s) y por cuenta; el resto, 600 pedidos por minuto por clave; pasarte da RATE_LIMITED (429, con Retry-After) — ver «Límites de velocidad». (4) Los de Meta, en el punto siguiente.

Los buckets se agregan en UTC; el timezone de la cuenta se devuelve solo para que vos armes el caption.

⚠⚠ LOS LÍMITES DE META SON OTRA COSA, Y SON LOS QUE TE VAN A FRENAR. Nosotros no te ponemos tope de mensajes; Meta sí te pone dos, y no se mezclan. (1) CONTACTOS — a cuánta gente DISTINTA le iniciás conversación en 24 h: 250 → 2.000 → 10.000 → 100.000 → sin límite, y se sube con verificación del negocio, volumen y calidad. ⚠ Desde el 7 de octubre de 2025 ese límite es por PORTAFOLIO de negocio, no por número: todos los números del mismo portafolio COMPARTEN el cupo. Si administrás números de varios clientes, dimensioná con esto. (2) RITMO — qué tan rápido salen: hasta 80 mensajes/segundo por número en la Cloud API (hasta 1.000 con el ascenso automático), y 20/segundo fijo para un número en Coexistence; pasarte devuelve el 130429 de Meta. Del lado nuestro no perdés mensajes por ir más rápido: la cola los absorbe y los drena, con reintentos e idempotencia. Verificado contra la documentación de Meta el 30/08/2026.

Los umbrales 70/90/100% llegan por webhook (usage.threshold_reached / connection.usage_threshold_reached). ⚠ El de CUENTA es relativo al cupo del plan, así que sin tope no se dispara; el POR NÚMERO (connection.usage_threshold_reached) sí, porque ese límite lo ponés vos.

Lo que cobra Meta es aparte de todo esto: ver Lo que cobra Meta y lo que cobra WAIA Connect.