Una conversación agrupa los mensajes con un contacto en un canal (WhatsApp, Instagram, Facebook o chat web).
La conversación
{
"id": 913,
"contact_id": 481,
"channel": "whatsapp",
"status": "active",
"bot_enabled": true,
"assigned_to_user_id": null,
"last_message_at": "2026-07-14T15:03:22.000Z",
"created_at": "2026-07-10T11:00:05.000Z"
}
| Campo | Qué es |
|---|---|
channel | whatsapp, instagram, facebook o web_widget (chat web) |
status | Estado de la conversación (abajo) |
bot_enabled | false si el agente IA está pausado en esta conversación (status: "handed_off"); true en cualquier otro estado |
assigned_to_user_id | Persona de tu equipo a la que está asignada, o null |
last_message_at | Fecha del último mensaje, en UTC |
Estados:
active: abierta; el agente IA responde si tienes uno.waiting: en espera.resolved: resuelta (cerrada).handed_off: el agente está pausado y la atiende una persona (bot_enabled: false).
Listar conversaciones
GET /api/v1/conversations
Scope: conversations:read
Devuelve primero las que tuvieron mensajes más recientes.
| Parámetro | Tipo | Descripción |
|---|---|---|
status | string | active, waiting, resolved o handed_off. Otro valor responde 400 |
channel | string | whatsapp, instagram, facebook o web_widget |
contact_id | number | Solo las conversaciones de ese contacto |
limit / offset | number | Paginación: limit de 1 a 100, 50 si no lo mandas |
curl "https://api.yolani.co/api/v1/conversations?status=active&limit=20" \
-H "Authorization: Bearer yol_TU_TOKEN"
Respuesta:
{
"success": true,
"data": [
{
"id": 913,
"contact_id": 481,
"channel": "whatsapp",
"status": "active",
"bot_enabled": true,
"assigned_to_user_id": null,
"last_message_at": "2026-07-14T15:03:22.000Z",
"created_at": "2026-07-10T11:00:05.000Z"
}
],
"meta": { "total": 34, "limit": 20, "offset": 0 }
}
Abrir una conversación
POST /api/v1/conversations
Scope: conversations:write
Abre una conversación de WhatsApp con un número. Es lo mismo que Nueva conversación en la bandeja:
- Si el contacto no existe, lo crea.
- Si ya tiene una conversación, reutiliza la más reciente (y la reabre si estaba resuelta). Si no, crea una nueva en la primera etapa de tu embudo.
- Si mandas
initial_message, se lo envía.
Responde 201 con la conversación en data. Toma su id para mandarle mensajes después.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
phone | string | Sí | Número con código de país (ej. 5215512345678). Se ignoran +, espacios y guiones; para México da igual 52 o 521 |
name | string | No | Nombre del contacto, si es nuevo |
initial_message | string | No | Texto que se le envía al abrir |
curl -X POST https://api.yolani.co/api/v1/conversations \
-H "Authorization: Bearer yol_TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone": "5215512345678",
"name": "Lucía Pérez",
"initial_message": "Hola Lucía, gracias por registrarte. ¿En qué te podemos ayudar?"
}'
El mensaje inicial no confirma su envío:
Si initial_message no sale (por ejemplo, no tienes WhatsApp conectado), la conversación se crea igual, la respuesta no lo avisa y el mensaje no queda guardado: si no aparece en GET /api/v1/conversations/:id/messages, no salió. Si necesitas saberlo al momento, abre la conversación sin initial_message y manda el texto con POST /api/v1/conversations/:id/messages, que sí responde con el status del envío. Si tu número está conectado por WhatsApp API y el cliente no te ha escrito en las últimas 24 horas, Meta no deja pasar un texto libre: abre la conversación sin mensaje y envía una plantilla.
Una conversación nueva o reabierta queda en active, con el agente encendido: si el cliente contesta, le responde tu agente. Si la que se reutiliza tenía el agente pausado (handed_off), sigue pausada. Para atenderla tú, pausa al agente con /bot.
Consultar una conversación
GET /api/v1/conversations/:id
Scope: conversations:read
Devuelve la conversación en data, o 404 con NOT_FOUND si no existe o no es de tu cuenta.
Cambiar el estado
PATCH /api/v1/conversations/:id
Scope: conversations:write
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
status | string | Sí | active, waiting o resolved |
# Cerrar una conversación
curl -X PATCH https://api.yolani.co/api/v1/conversations/913 \
-H "Authorization: Bearer yol_TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status": "resolved"}'
Responde con la conversación actualizada. Todo cambio dispara el webhook conversation.updated, y resolverla dispara además conversation.closed.
Para pausar al agente usa /bot:
handed_off no se acepta aquí: para que una persona atienda, usa POST /api/v1/conversations/:id/bot con enabled: false, que además corta la respuesta que el agente estuviera escribiendo. Y al revés: si la conversación estaba en handed_off, pasarla aquí a active, waiting o resolved vuelve a encender al agente.
Mover de etapa en el embudo
POST /api/v1/conversations/:id/stage
Scope: conversations:write
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
stage_id | number | Sí | Etapa a la que pasa la conversación. Los ids salen de GET /api/v1/pipelines |
curl -X POST https://api.yolani.co/api/v1/conversations/913/stage \
-H "Authorization: Bearer yol_TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"stage_id": 12}'
Respuesta:
{
"success": true,
"data": {
"conversation_id": 913,
"stage_id": 12,
"stage_name": "Cita agendada",
"pipeline_id": 2,
"previous_stage_id": 11
}
}
Es lo mismo que mover la tarjeta en el embudo: queda en el historial de la conversación, corre las acciones automáticas que tenga esa etapa y dispara el webhook conversation.stage_changed con "source": "system". Si la etapa es de otro embudo, la conversación se cambia a ese embudo.
| HTTP | Código | Motivo |
|---|---|---|
| 400 | VALIDATION_ERROR | Falta stage_id o no es un número |
| 404 | STAGE_NOT_FOUND | La etapa no existe, está inactiva o no es de tu cuenta |
| 404 | NOT_FOUND | La conversación no existe o no es de tu cuenta |
Listar embudos y etapas
GET /api/v1/pipelines
Scope: conversations:read
Devuelve tus embudos activos, cada uno con sus etapas activas en orden.
curl https://api.yolani.co/api/v1/pipelines \
-H "Authorization: Bearer yol_TU_TOKEN"
Respuesta:
{
"success": true,
"data": [
{
"id": 2,
"name": "Ventas",
"is_default": true,
"stages": [
{ "id": 10, "name": "Nuevo contacto", "position": 0, "is_final": false, "pipeline_id": 2, "pipeline_name": "Ventas" },
{ "id": 11, "name": "Interesada", "position": 1, "is_final": false, "pipeline_id": 2, "pipeline_name": "Ventas" },
{ "id": 12, "name": "Cita agendada", "position": 2, "is_final": false, "pipeline_id": 2, "pipeline_name": "Ventas" },
{ "id": 13, "name": "Clienta", "position": 3, "is_final": true, "pipeline_id": 2, "pipeline_name": "Ventas" }
]
}
]
}
is_default marca el embudo principal; is_final, la etapa de cierre. Cada etapa repite pipeline_id y pipeline_name para que puedas armar una lista plana ("Ventas › Interesada").
Encender o pausar el agente IA
POST /api/v1/conversations/:id/bot
Scope: bot:manage
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
enabled | boolean | Sí | true enciende al agente, false lo pausa |
reason | string | No | Motivo de la pausa. Si no lo mandas, queda "Pausado via API" |
# Pausar al agente para que atienda una persona
curl -X POST https://api.yolani.co/api/v1/conversations/913/bot \
-H "Authorization: Bearer yol_TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled": false, "reason": "La clienta pidió hablar con una asesora"}'
Respuesta al pausar:
{
"success": true,
"data": { "conversation_id": 913, "bot_enabled": false }
}
Respuesta al encender (trae el agente que va a contestar):
{
"success": true,
"data": { "conversation_id": 913, "bot_enabled": true, "assistant_id": 52 }
}
- Pausar pasa la conversación a
handed_off, corta la respuesta que el agente estuviera escribiendo y detiene las automatizaciones en curso de esa conversación. El agente vuelve solo cuando se cumple el plazo de Regreso de tu cuenta, igual que cuando lo apagas desde la bandeja (ver Cuándo responde el agente y cuándo tú). - Encender la deja en
activey el agente contesta desde el siguiente mensaje. Si tu cuenta no tiene ningún agente activo, responde400conNO_ASSISTANT.
Cada cambio dispara el webhook conversation.bot.enabled o conversation.bot.disabled.