Mensajería

Todos los endpoints de envío retornan 202 Accepted inmediatamente. El mensaje se encola y se envía con el delay anti-ban del carril elegido.

Carriles (Anti-ban)

Cada mensaje se envía por uno de tres carriles. El carril controla el delay y los límites de envío para proteger el número de WhatsApp.

Lane	Delay	Límite/hora	Límite/día	Usar para
`urgent`	1–2s	150 msg	1000 msg	OTP, alertas críticas
`normal`	3–8s	80 msg	500 msg	Conversación, notificaciones
`bulk`	8–15s	30 msg	200 msg	Campañas masivas

Límites por instancia, no por tenant.
urgent siempre se procesa antes que normal o bulk.
Mensajes que exceden el límite esperan en cola, no se descartan.
Default si no se especifica: normal.

Texto

Soporta spintax: {Hola|Hey}! se resuelve al azar en cada envío.

json

POST /message/text

{
  "instanceName": "acme__soporte__main",
  "to": "5491112345678",
  "text": "{Hola|Hey}! Tu código es 1234.",
  "lane": "normal"
}

// Respuesta 202
{ "id": "uuid-del-mensaje", "status": "pending", "lane": "normal", "queuedAt": "2026-03-15T10:30:00.000Z" }

Imagen

El gateway descarga la imagen desde la URL. Debe ser pública y accesible desde internet.

json

POST /message/image

{
  "instanceName": "acme__soporte__main",
  "to": "5491112345678",
  "imageUrl": "https://cdn.example.com/foto.jpg",
  "caption": "Mirá esto",
  "lane": "normal"
}

Documento

json

POST /message/document

{
  "instanceName": "acme__soporte__main",
  "to": "5491112345678",
  "documentUrl": "https://cdn.example.com/factura.pdf",
  "fileName": "factura-001.pdf",
  "caption": "Tu factura adjunta",
  "lane": "normal"
}

Audio (nota de voz)

json

POST /message/audio

{
  "instanceName": "acme__soporte__main",
  "to": "5491112345678",
  "audioUrl": "https://cdn.example.com/audio.ogg",
  "lane": "normal"
}
// Formato recomendado: OGG/Opus (se muestra como nota de voz PTT)

Video

json

POST /message/video

{
  "instanceName": "acme__soporte__main",
  "to": "5491112345678",
  "videoUrl": "https://cdn.example.com/video.mp4",
  "caption": "Miralo",
  "lane": "normal"
}

Encuestas (Polls)

json

POST /message/poll

{
  "instanceName": "acme__soporte__main",
  "to": "5491112345678",
  "name": "¿Qué opinas del servicio?",
  "options": ["Excelente", "Bueno", "Malo"],
  "selectableCount": 1,
  "lane": "normal"
}

Stickers

json

POST /message/sticker

{
  "instanceName": "acme__soporte__main",
  "to": "5491112345678",
  "stickerUrl": "https://cdn.example.com/sticker.webp",
  "lane": "normal"
}

Estados (Stories)

Publicación instantánea que no pasa por el motor Anti-ban.

json

POST /status

{
  "instanceName": "acme__soporte__main",
  "type": "text",
  "text": "¡Nuevo servicio disponible! 🚀"
}
// También soporta "image" o "video" junto a "url" y "caption". Se publican instantáneamente sin pasar por los delays anti-ban.

Route (round-robin)

Auto-selecciona una instancia conectada del pool del cliente. Útil cuando un cliente tiene múltiples números. La respuesta incluye instanceName para saber qué número se eligió.

json

POST /message/route

{
  "tenantId": "acme",
  "clientId": "soporte",
  "to": "5491112345678",
  "type": "text",
  "text": "Hola!",
  "lane": "normal"
}

// Respuesta 202 — incluye la instancia seleccionada automáticamente
{ "id": "uuid", "status": "pending", "lane": "normal", "instanceName": "acme__soporte__num2" }

Estado de un mensaje

json

GET /message/3b2e1f4a-8c9d-4e2f-b7a1-0d5c6e3f9b2a

// Respuesta 200
{
  "id": "3b2e1f4a-8c9d-4e2f-b7a1-0d5c6e3f9b2a",
  "instanceName": "acme__soporte__main",
  "lane": "normal",
  "to": "5491112345678",
  "type": "text",
  "status": "sent",
  "createdAt": "2026-03-15T10:30:00.000Z",
  "sentAt": "2026-03-15T10:30:07.000Z",
  "error": null
}

status	Descripción
`pending`	En cola, esperando ser enviado
`sent`	Enviado correctamente
`failed`	Error — ver campo `error`

Spintax

Genera variantes de texto para evitar mensajes repetitivos. Se resuelve aleatoriamente en el momento del envío. Soporta anidamiento.

Soportado en: campo text · campo caption (en image, document, video).

bash

# Simple
{Hola|Hey|Buenas}! {¿Cómo estás|Qué tal}?
→ "Hey! Qué tal?"

# Anidado
{Buen{os días|as tardes}|Hola}!
→ "Buenas tardes!"

Referencia rápida de campos

Campo	Formato	Ejemplo
`instanceName`	`tenant__client__label`	`acme__soporte__main`
`to`	Internacional sin `+`	`5491112345678`
`lane`	`urgent` / `normal` / `bulk`	`normal`
`type` (route)	`text / image / document / audio / video`	`text`
`webhookSecret`	String, mín. 16 caracteres	`mi-secreto-seguro-32`
Timestamps	ISO 8601 UTC	`2026-03-15T10:30:00.000Z`
IDs de mensaje	UUID v4	`3b2e1f4a-...`