Mensajes

Leer los mensajes de una conversación y enviar texto o archivos por la API. El mensaje sale por el canal de la conversación (WhatsApp, Instagram, Facebook o chat web) sin que tengas que elegirlo.

Listar mensajes

GET /api/v1/conversations/:id/messages

Scope: conversations:read

Devuelve primero los más recientes. Pagina con limit (de 1 a 100, 50 si no lo mandas) y offset.

curl "https://api.yolani.co/api/v1/conversations/913/messages?limit=20" \
  -H "Authorization: Bearer yol_TU_TOKEN"

Respuesta:

{
  "success": true,
  "data": [
    {
      "id": 15204,
      "conversation_id": 913,
      "direction": "inbound",
      "channel": "whatsapp",
      "type": "text",
      "content": "¿Tienen lugar para un tinte el sábado?",
      "media_url": null,
      "status": "delivered",
      "sent_by_bot": false,
      "created_at": "2026-07-14T15:03:22.000Z"
    }
  ],
  "meta": { "total": 42, "limit": 20, "offset": 0 }
}
CampoValores
directioninbound (lo escribió el cliente) u outbound (salió de tu cuenta)
typetext, image, audio, video, document, location o sticker
statuspending, sent, delivered, read, played o failed
sent_by_bottrue si lo escribió tu agente IA
media_urlEn mensajes con archivo, la ruta del archivo dentro de Yolani (/api/media/...). Hoy no se puede descargar con la API key: el archivo se ve desde la bandeja

Enviar un mensaje de texto

POST /api/v1/conversations/:id/messages

Scope: messages:send

CampoTipoRequeridoDescripción
textstringSí (o media_url)Texto del mensaje
client_request_idstringNoUn id tuyo para no duplicar el mensaje si reintentas la petición
curl -X POST https://api.yolani.co/api/v1/conversations/913/messages \
  -H "Authorization: Bearer yol_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Sí, el sábado a las 11:00 tenemos lugar. ¿Te lo aparto?"}'

Respuesta (201):

{
  "success": true,
  "data": {
    "message_id": 15205,
    "conversation_id": 913,
    "channel": "whatsapp",
    "type": "text",
    "status": "sent",
    "already_processed": false
  }
}

Revisa status en la respuesta:

  • sent: salió por el canal.
  • pending: WhatsApp no estaba disponible en ese momento y el mensaje quedó en cola; Yolani lo reintenta solo.
  • failed: no salió. El mensaje queda guardado en la conversación como fallido.

Idempotencia:

Si mandas client_request_id y repites la petición con el mismo valor en la misma conversación, no se envía otra vez: la API responde 200 con already_processed: true y el mismo message_id. Aplica a mensajes de texto; los archivos no lo usan.

La ventana de 24 horas de WhatsApp API:

Si la conversación es por WhatsApp API y el cliente no te ha escrito en las últimas 24 horas, Meta no entrega un texto libre: el mensaje queda como failed, en la respuesta o unos segundos después (consúltalo con GET .../messages). Para escribirle fuera de esa ventana usa una plantilla.

Enviar un archivo

Mismo endpoint, con media_url en vez de text. Yolani descarga el archivo y lo manda por el canal de la conversación.

CampoTipoRequeridoDescripción
media_urlstringSíURL pública del archivo (imagen, video, audio o documento)
captionstringNoTexto que acompaña al archivo
filenamestringNoNombre con el que llega el archivo (útil en documentos). Si no lo mandas, se toma de la URL
curl -X POST https://api.yolani.co/api/v1/conversations/913/messages \
  -H "Authorization: Bearer yol_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "media_url": "https://miweb.com/lista-de-precios-2026.pdf",
    "caption": "Te comparto nuestra lista de precios",
    "filename": "lista-de-precios-2026.pdf"
  }'

Respuesta (201):

{
  "success": true,
  "data": {
    "message_id": 15206,
    "conversation_id": 913,
    "channel": "whatsapp",
    "type": "document",
    "status": "sent"
  }
}
  • El archivo pesa como máximo 15 MB y se tiene que descargar en menos de 20 segundos.
  • La URL tiene que ser pública: no se aceptan localhost ni direcciones de redes privadas, tampoco al seguir una redirección.
  • El tipo (image, video, audio o document) sale del Content-Type con el que responde tu servidor. Si sirve todo como application/octet-stream, llega como documento.
  • Si mandas text y media_url juntos, se envía solo el archivo: pon el texto en caption.
HTTPCódigoMotivo
413MEDIA_TOO_LARGEEl archivo pasa de 15 MB
422MEDIA_DOWNLOAD_FAILEDNo se pudo descargar media_url (la respuesta dice por qué, por ejemplo media_url devolvio HTTP 404)

Tu agente y los mensajes de la API

Un texto o un archivo que envías por la API cuenta como si lo escribiera alguien de tu equipo desde el celular del negocio: la conversación no pasa a manual, pero el agente se aparta un rato para no contestarle al cliente encima de ti. Es el mismo rato de Agentes → Ajustes → Cuando contestas tú (30 minutos si no lo cambiaste): si el cliente responde dentro de ese plazo, el agente no le contesta. Ver Cuándo responde el agente y cuándo tú.

  • Para que el agente conteste desde ya, enciéndelo con POST /api/v1/conversations/:id/bot y enabled: true: eso cancela el rato.
  • Para que no conteste en absoluto, páusalo con el mismo endpoint y enabled: false.
  • Una plantilla que sale como plantilla de WhatsApp API y el initial_message de POST /api/v1/conversations no apartan al agente.

Cada mensaje que sale dispara el webhook message.sent, y cada mensaje del cliente, message.received. Ver Webhooks.

Ejemplo en JavaScript

const response = await fetch(
  'https://api.yolani.co/api/v1/conversations/913/messages',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.YOLANI_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text: 'Tu cita quedó confirmada para el sábado a las 11:00.',
      client_request_id: 'cita-2291-confirmacion',
    }),
  },
);
const result = await response.json();
if (!result.success) throw new Error(result.error.message);
console.log(result.data.status); // "sent", "pending" o "failed"

Ejemplo en Python

import os
import requests

response = requests.post(
    "https://api.yolani.co/api/v1/conversations/913/messages",
    headers={"Authorization": f"Bearer {os.environ['YOLANI_API_KEY']}"},
    json={
        "text": "Tu cita quedó confirmada para el sábado a las 11:00.",
        "client_request_id": "cita-2291-confirmacion",
    },
    timeout=30,
)
result = response.json()
print(result["data"]["status"] if result["success"] else result["error"])