Mensajes

Envía y consulta mensajes de una conversación. El mensaje sale por el canal de la conversación (WhatsApp, Instagram, Facebook o widget web) sin que tengas...

Listar mensajes

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

Scope: conversations:read

Devuelve los mensajes más recientes primero. Paginación con limit 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 envío a domicilio?",
      "media_url": null,
      "status": "delivered",
      "sent_by_bot": false,
      "created_at": "2026-07-14T15:03:22.000Z"
    }
  ],
  "meta": { "total": 42, "limit": 20, "offset": 0 }
}

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_idstringNoID propio para idempotencia (evita duplicados en reintentos)
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í, tenemos envío a domicilio sin costo en pedidos mayores a $500."}'

Respuesta:

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

Idempotencia:

Si envías client_request_id, reintentar la misma petición no duplica el mensaje: la API responde 200 con already_processed: true.

Enviar multimedia

Mismo endpoint, pero con media_url en lugar de text. Yolani descarga el archivo y lo envía por el canal.

CampoTipoRequeridoDescripción
media_urlstringSíURL pública del archivo (imagen, video, audio o documento)
captionstringNoTexto que acompaña al archivo
filenamestringNoNombre del archivo (para documentos)
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/catalogo-2026.pdf",
    "caption": "Te comparto nuestro catálogo actualizado",
    "filename": "catalogo-2026.pdf"
  }'

Límites: archivos de hasta 15 MB. La URL debe ser pública (no localhost ni redes privadas).

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 pedido #1042 fue enviado. Llega mañana.',
      client_request_id: 'pedido-1042-envio',
    }),
  },
);
const result = await response.json();

Ejemplo en Python

import requests

response = requests.post(
    "https://api.yolani.co/api/v1/conversations/913/messages",
    headers={"Authorization": f"Bearer {YOLANI_API_KEY}"},
    json={"text": "Tu pedido #1042 fue enviado. Llega mañana."},
)
result = response.json()