Ir al contenido

API y SDK

Límites

Los límites de la API de Messajo, del envío por número, de Meta y de la retención de datos.

Cada clave y cada organización tienen un límite de solicitudes por minuto. Los dos valen a la vez: la llamada pasa solo si cabe en ambos.

Alcance Límite por defecto
Por clave de API 600 solicitudes/min (ajustable por clave hasta 6.000/min)
Por organización (todas las claves sumadas) suma del caudal de las conexiones activas x 60 x 1,25, mínimo 1.200 solicitudes/min

Los dos límites valen para los dos tipos de clave (organización mj_ y conexión mjc_). El límite por clave es de cada clave: cada clave de conexión tiene su propio contador de 600 solicitudes/min. El límite de la organización es uno solo y suma el tráfico de todas las claves, incluidas las de conexión, así que varias claves de conexión juntas siguen compartiendo el mismo caudal de la organización.

Toda respuesta de la API /v1 trae los encabezados de la ventana actual:

Encabezado Qué es
X-RateLimit-Limit Límite de la ventana
X-RateLimit-Remaining Cuántas llamadas todavía caben en la ventana
X-RateLimit-Reset Cuándo se reinicia la ventana (Unix, en segundos)

Al superar el límite, la respuesta es 429 con el código rate_limited, el encabezado Retry-After (segundos) y el campo retry_after_ms en el cuerpo. Espera ese tiempo antes de repetir.

El límite de la organización acompaña a sus conexiones: dos números de 80 y 20 mensajes/s dan 7.500 solicitudes/min (100 x 60 x 1,25). Instagram y Messenger solo suman si tienen caudal registrado. El valor se recalcula cada 60 s, así que conectar o quitar un número tarda hasta 1 minuto en aplicarse; X-RateLimit-Limit muestra el límite vigente. Los demás valores pueden cambiar por plan.

Cada número tiene un rendimiento máximo, que depende del modo de la conexión. Messajo lee el rendimiento junto con el estado del número, cada 15 minutos, y lo muestra en Velocidad en la página de la conexión:

Modo Rendimiento
Coexistencia (app del celular + API) 20 mensajes/s
Solo API 80 mensajes/s
Solo API, con rendimiento alto liberado por Meta 1.000 mensajes/s (Meta lo sube sola)

Cada número tiene un balde de fichas con el rendimiento como capacidad (20, 80 o 1.000), que se rellena a ese ritmo por segundo. Cada llamada que va a Meta gasta una ficha: el envío, por la capa simple o por el espejo, y el typing. Sin fichas, Messajo responde 429 con el código connection_rate_limited, el encabezado Retry-After y el retry_after_ms en el cuerpo, sin llamar a Meta. Nada se encola: espera ese tiempo y repite con la misma Idempotency-Key.

Si la propia Meta rechaza por rendimiento (130429, 80007 o 4 en meta_code), la respuesta es 429 meta_rate_limited. Como Meta no procesó el pedido, Messajo repite solo cuando la espera cabe en 2,5 s; si no, devuelve el error con el retry_after_ms que informe Meta.

Meta limita a cuántos usuarios únicos llega el portafolio (Business Manager) con mensajes iniciados por la empresa en 24 horas móviles. El límite es del portafolio y lo comparten todos sus números.

Los escalones son 250 → 2.000 → 10.000 → 100.000 → ilimitado. Para subir:

  • verificar la empresa en el portafolio, o
  • mantener buena calidad y enviar al menos a la mitad del límite actual dentro de 7 días.

Meta reevalúa el portafolio cada 6 horas y sube el escalón sola cuando se cumplen las condiciones. Messajo lee el escalón actual (campo whatsapp_business_manager_messaging_limit del número) junto con el estado y lo muestra en Nivel de envío en la página de la conexión; cuando cambia, sale connection.updated con reason: "limit_changed". Las respuestas dentro de una conversación abierta por el contacto no cuentan para este límite. Las campañas se detienen solas en el 95 % del nivel y vuelven cuando se libera.

Detalles oficiales: límites de mensajes de Meta.

Meta también limita cuántos mensajes envía un número al mismo contacto en poco tiempo (del orden de un mensaje cada 6 segundos, con pequeñas ráfagas). Por encima de eso, la respuesta es 429 pair_rate_limited, con 131056 en meta_code y un retry_after_ms de 6.000: espera y espacia los envíos a ese contacto. Messajo nunca repite este error solo.

Canal Regla
WhatsApp Hasta 24 horas después del último mensaje del contacto, cualquier mensaje. Fuera de eso, solo plantilla aprobada.
Instagram y Messenger Hasta 24 horas después del último mensaje del contacto; 7 días después de que el contacto responda a un anuncio. Con tag: "human_agent" (solo respuestas de una persona), hasta 7 días. Fuera de eso, 422 antes de llamar a Meta.

En WhatsApp, Messajo comprueba la ventana antes de llamar a Meta: un mensaje que no es plantilla, fuera de la ventana, vuelve 422 outside_service_window, con el fin de la ventana en details[0].message. Solo el mensaje del contacto abre la ventana; lo que envías desde la app del celular en coexistencia no la abre.

Cada cuenta de Instagram y cada Página de Messenger tienen un balde de fichas, como los números de WhatsApp. Sin ficha, la respuesta es 429 connection_rate_limited, sin llamar a Meta.

Canal Texto, reacción, me gusta, botones y tarjetas Archivos (imagen, images, audio, video, PDF)
Instagram 100 mensajes/s 10 mensajes/s (también gasta una ficha de texto)
Messenger 100 mensajes/s 100 mensajes/s
Límite Instagram Messenger
Texto 1.000 bytes 2.000 caracteres
Imágenes por mensaje hasta 10 (images) 1
Adjunto imagen hasta 8 MB; audio, video y PDF hasta 25 MB 25 MB
Publicaciones 100 por cuenta en 24 h (publicaciones) —

Si la propia Meta rechaza por rendimiento (4, 17, 32, 613 o 80006), la respuesta es 429 meta_rate_limited con el retry_after_ms que informe Meta. No hay envíos masivos ni campañas en Instagram y Messenger: Meta no lo permite. Los números de arriba vienen de la documentación de la Plataforma de Instagram y de la Plataforma de Messenger y todavía se confirman en una cuenta real.

Límite Valor
Solicitud de permiso de llamada (Meta) 1 cada 24 h y 2 cada 7 días para el mismo contacto (Llamadas)
SDP de una llamada 64 KiB
Participantes por grupo 8 (Grupos)
JSON de un Flow 10 MiB; PUT /v1/flows/{id}/json hasta 30 por minuto por organización
Intercambios en el endpoint de un Flow 1.200 por minuto por Flow; tu handler tiene 7 s y hasta 256 KiB de respuesta (Flows)
Ítems por pedido 100 (Ventas)
Subida de medios (POST /v1/media) 120 por minuto por organización
Ruta Máximo
/v1 (JSON) 1 MiB
POST /v1/media 100 MiB
POST /v1/campaigns/{id}/recipients 20 MiB
PUT /v1/flows/{id}/json 10 MiB
Panel (/rpc) 2 MiB

Por encima de eso, la respuesta es 413 body_too_large, sin procesar nada.

Dato Plazo
Evento bruto recibido de Meta 7 días
Eventos y registro de las entregas 30 días (o el plazo de la organización, si es menor)
Logs del panel (solicitudes de la API) 30 días (o el plazo de la organización, si es menor)
Mensajes, medios, conversaciones y contactos 90 días por defecto; el propietario elige de 7 hasta el tope de la instancia

Después del plazo, el dato se borra en la purga diaria. Detalles en Datos y privacidad.

Envía el encabezado Idempotency-Key (un valor único por operación, por ejemplo un UUID) en las llamadas que crean algo, como el envío de mensajes. La clave vale por 24 horas: repetir la misma clave en ese plazo devuelve la respuesta original, sin ejecutar de nuevo. Así se repite un envío con seguridad después de un timeout.