Conversaciones: leer, paginar y sincronizar tu CRM

Una conversación es el hilo con un número de teléfono. Es única por empresa y número, así que el mismo cliente siempre cae en el mismo hilo.

Los teléfonos van en formato internacional

Siempre +51987654321 (E.164 con +). Se acepta lo que normalice a eso, como "+51 987-654-321".

Listar conversaciones

GET/conversationsscope: conversations:read

Devuelve las conversaciones de tu empresa, de la más reciente a la más antigua.

Parámetros de consulta

Campo	Tipo	Descripción
`status`	string	`IN_PROGRESS` o `CLOSED`.
`phone`	string	Filtra por número, en formato internacional.
`updatedAfter`	ISO 8601	Solo las modificadas después de esa fecha. Combinalo con `order=updatedAt`.
`order`	string	`createdAt` (por defecto), `updatedAt` o `lastMessageAt`.
`include`	string	`customFields` agrega la ficha del cliente. Requiere `custom_fields:read`.
`limit`	number	Entre 1 y 100. Por defecto 20.
`cursor`	string	El `nextCursor` de la página anterior.

curl "https://www.flujoschat.foo/api/public/v1/conversations?status=IN_PROGRESS&limit=50" \
  -H "Authorization: Bearer fjc_live_..."

Respuesta · 200

{
  "success": true,
  "message": "Operación exitosa",
  "data": {
    "conversations": [
      {
        "id": "3f2b…",
        "customerPhone": "+51987654321",
        "customerName": "Ana Pérez",
        "status": "IN_PROGRESS",
        "engagementLevel": "INTERESADO_INTERACTUADOR",
        "hasPurchaseConfirmation": false,
        "botPaused": false,
        "aiControlled": false,
        "aiTransferReason": null,
        "lastMessageAt": "2026-07-26T14:31:09.000Z",
        "createdAt": "2026-07-20T09:02:11.000Z",
        "updatedAt": "2026-07-26T14:31:09.000Z"
      }
    ],
    "nextCursor": "3f2b…"
  }
}

Sincronización incremental

Para mantener tu CRM al día sin volver a leer todo el historial, pedí solo lo que cambió:

curl "https://www.flujoschat.foo/api/public/v1/conversations\
?updatedAfter=2026-07-26T10:00:00Z&order=updatedAt&include=customFields&limit=100" \
  -H "Authorization: Bearer fjc_live_..."

Escribir un campo personalizado también toca updatedAt, así que ese cambio también aparece.

Para tiempo real, mejor webhooks

Esta sincronización sirve para reconciliar y para arrancar. Si querés reaccionar en el momento, suscribite a los eventos y dejá de preguntar.

Detalle

GET/conversations/{id}scope: conversations:read

Acepta ?include=customFields.

Actualizar

PATCH/conversations/{id}scope: conversations:write

Actualización parcial del estado operativo. Mandá al menos un campo.

Cuerpo

Campo	Tipo	Descripción
`status`	string	`IN_PROGRESS` o `CLOSED`. No existe `OPEN`.
`botPaused`	boolean	Con true, ningún flujo, regla ni IA responde automáticamente.
`customerName`	string \| null	Hasta 120 caracteres.

# Cerrar el chat y devolver el control al bot
curl -X PATCH https://www.flujoschat.foo/api/public/v1/conversations/$CONVERSATION_ID \
  -H "Authorization: Bearer fjc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"CLOSED","botPaused":false}'

Campos de estado que te importan

botPaused — un humano (o tu sistema) está atendiendo.
aiControlled — la conversación la lleva un agente de IA.
aiTransferReason — por qué la IA la dejó esperando a una persona. Si no es null, alguien tiene que entrar.
engagementLevel y hasPurchaseConfirmation — qué tan avanzado está el cliente, calculado por la plataforma.

Historial de mensajes

GET/conversations/{id}/messagesscope: conversations:read

Del más reciente al más antiguo, con el mismo esquema de cursor.

Respuesta · 200

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "9c1e…",
        "conversationId": "3f2b…",
        "direction": "INBOUND",
        "type": "TEXT",
        "text": "Hola, ¿ya salió mi pedido?",
        "content": { "body": "Hola, ¿ya salió mi pedido?" },
        "status": "DELIVERED",
        "sentAt": "2026-07-26T14:31:09.000Z",
        "deliveredAt": "2026-07-26T14:31:10.000Z",
        "readAt": null,
        "createdAt": "2026-07-26T14:31:09.000Z"
      }
    ],
    "nextCursor": null
  }
}

text es la versión legible (útil para imágenes o botones, donde el cuerpo crudo no es texto). content es el payload tal cual, por si necesitás el detalle.

Preguntas frecuentes

¿Cómo sincronizo solo las conversaciones que cambiaron?

Usá updatedAfter con order=updatedAt: devuelve las conversaciones cuyo updatedAt es posterior a la marca que le pasés. Guardá el updatedAt más alto de cada corrida y usalo como punto de partida de la siguiente. Con el orden por defecto (createdAt) solo detectarías conversaciones nuevas, no las modificadas.

¿Por qué la API no tiene el estado OPEN?

Una conversación solo puede estar IN_PROGRESS o CLOSED. "Abierta" es una etiqueta de la interfaz, no un estado de la base: mandar status OPEN devuelve 400 INVALID_STATUS.

¿Cómo evito que el bot responda mientras mi sistema atiende el chat?

Hacé PATCH /conversations/{id} con botPaused: true. Con eso ningún flujo, regla ni agente de IA responde automáticamente en esa conversación, hasta que lo vuelvas a poner en false.