Conversaciones

Una conversación agrupa los mensajes con un contacto en un canal (WhatsApp, Instagram, Facebook, widget web).

Listar conversaciones

GET /api/v1/conversations

Scope: conversations:read

ParámetroTipoDescripción
statusstringactive, waiting, resolved o handed_off
channelstringwhatsapp, instagram, facebook, web
contact_idnumberConversaciones de un contacto específico
limit / offsetnumberPaginación (límite máximo 100)
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 }
}

Estados:

  • active: conversación abierta, el agente IA responde si está configurado
  • waiting: esperando respuesta del cliente
  • resolved: conversación cerrada
  • handed_off: agente IA pausado, un humano atiende (bot_enabled: false)

Abrir una conversación

POST /api/v1/conversations

Scope: conversations:write

Crea (o reactiva) una conversación de WhatsApp con un número. Si el contacto no existe, se crea automáticamente. Puedes incluir un mensaje inicial.

CampoTipoRequeridoDescripción
phonestringSíNúmero con código de país (ej. 5215512345678)
namestringNoNombre del contacto si es nuevo
initial_messagestringNoMensaje que se 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": "Juan Rodríguez",
    "initial_message": "Hola Juan, gracias por registrarte. ¿En qué te podemos ayudar?"
  }'

Consultar una conversación

GET /api/v1/conversations/:id

Scope: conversations:read

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"}'

Para pausar el agente IA usa `/bot`:

Cambiar el estado no pausa el agente IA. Si quieres que un humano atienda, usa POST /conversations/:id/bot con enabled: false (hace el handoff completo: corta respuestas en curso y notifica al inbox).

Activar o pausar el agente IA

POST /api/v1/conversations/:id/bot

Scope: bot:manage

CampoTipoRequeridoDescripción
enabledbooleanSítrue activa el agente IA, false lo pausa
reasonstringNoMotivo del cambio (visible en el inbox)
# Pausar el bot para que un humano atienda
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": "Cliente pidió hablar con un asesor"}'

Respuesta:

{
  "success": true,
  "data": { "conversation_id": 913, "bot_enabled": false }
}