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 }
}
| Campo | Valores |
|---|---|
direction | inbound (lo escribió el cliente) u outbound (salió de tu cuenta) |
type | text, image, audio, video, document, location o sticker |
status | pending, sent, delivered, read, played o failed |
sent_by_bot | true si lo escribió tu agente IA |
media_url | En 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
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
text | string | Sí (o media_url) | Texto del mensaje |
client_request_id | string | No | Un 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.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
media_url | string | Sí | URL pública del archivo (imagen, video, audio o documento) |
caption | string | No | Texto que acompaña al archivo |
filename | string | No | Nombre 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
localhostni direcciones de redes privadas, tampoco al seguir una redirección. - El tipo (
image,video,audioodocument) sale delContent-Typecon el que responde tu servidor. Si sirve todo comoapplication/octet-stream, llega como documento. - Si mandas
textymedia_urljuntos, se envía solo el archivo: pon el texto encaption.
| HTTP | Código | Motivo |
|---|---|---|
| 413 | MEDIA_TOO_LARGE | El archivo pasa de 15 MB |
| 422 | MEDIA_DOWNLOAD_FAILED | No 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/botyenabled: 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_messagedePOST /api/v1/conversationsno 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"])