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.
API de Messajo
Sección titulada «API de Messajo»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.
Envío por número
Sección titulada «Envío por número»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.
Límite de mensajes de Meta
Sección titulada «Límite de mensajes de 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.
Límite por par
Sección titulada «Límite por par»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.
Ventanas
Sección titulada «Ventanas»| Canal | Regla |
|---|---|
| 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.
Instagram y Messenger
Sección titulada «Instagram y Messenger»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) |
|---|---|---|
| 100 mensajes/s | 10 mensajes/s (también gasta una ficha de texto) | |
| Messenger | 100 mensajes/s | 100 mensajes/s |
| Límite | 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.
Llamadas, grupos, Flows y pedidos
Sección titulada «Llamadas, grupos, Flows y pedidos»| 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 |
Tamaño del cuerpo
Sección titulada «Tamaño del cuerpo»| 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.
Retención
Sección titulada «Retención»| 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.
Idempotency-Key
Sección titulada «Idempotency-Key»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.