Conversaciones

Listar y consultar conversaciones, abrir una conversación de WhatsApp por teléfono, cambiar su estado, moverla de etapa en el embudo y encender o pausar al agente IA desde la API.

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"
}
CampoQué es
channelwhatsapp, instagram, facebook o web_widget (chat web)
statusEstado de la conversación (abajo)
bot_enabledfalse si el agente IA está pausado en esta conversación (status: "handed_off"); true en cualquier otro estado
assigned_to_user_idPersona de tu equipo a la que está asignada, o null
last_message_atFecha 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ámetroTipoDescripción
statusstringactive, waiting, resolved o handed_off. Otro valor responde 400
channelstringwhatsapp, instagram, facebook o web_widget
contact_idnumberSolo las conversaciones de ese contacto
limit / offsetnumberPaginació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.

CampoTipoRequeridoDescripción
phonestringSíNúmero con código de país (ej. 5215512345678). Se ignoran +, espacios y guiones; para México da igual 52 o 521
namestringNoNombre del contacto, si es nuevo
initial_messagestringNoTexto 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

CampoTipoRequeridoDescripción
statusstringSí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

CampoTipoRequeridoDescripción
stage_idnumberSí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.

HTTPCódigoMotivo
400VALIDATION_ERRORFalta stage_id o no es un número
404STAGE_NOT_FOUNDLa etapa no existe, está inactiva o no es de tu cuenta
404NOT_FOUNDLa 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

CampoTipoRequeridoDescripción
enabledbooleanSítrue enciende al agente, false lo pausa
reasonstringNoMotivo 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 active y el agente contesta desde el siguiente mensaje. Si tu cuenta no tiene ningún agente activo, responde 400 con NO_ASSISTANT.

Cada cambio dispara el webhook conversation.bot.enabled o conversation.bot.disabled.