> ## Documentation Index
> Fetch the complete documentation index at: https://dev.docs.1to1ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversación e hilo

> Consulta el estado de una conversación y lee su hilo de mensajes y eventos

<Info>
  **Endpoint** · `GET /conversation` (detalle) y `GET /conversation/messages` (hilo)
</Info>

<Note>
  Endpoints de **solo consulta**: devuelven información y no modifican nada. No se mandan dentro del array `actions` — se llaman directo.
</Note>

Son las dos lecturas que dan contexto antes de operar sobre una conversación. `GET /conversation` responde en qué estado está (ventana de 24h, buzón, empleado AI, etiquetas) y quién es el contacto; `GET /conversation/messages` responde qué se dijo, en qué orden y quién lo dijo. Con lo primero decides **qué acción es válida** (por ejemplo, si la ventana está cerrada solo puedes enviar una plantilla); con lo segundo redactas el mensaje con el historial a la vista.

Ambos identifican la conversación con la misma referencia que el resto de la API, pero pasada por **query params** en vez del cuerpo: exactamente uno de `phone`, `username`, `whatsapp_user_id` o `uuid`, más `channel`.

## Detalle de la conversación

```http theme={null}
GET /conversation
```

**Parámetros**

* `phone` — teléfono en formato E.164. Se normaliza a dígitos antes del lookup.
* `username` — username público de WhatsApp. Se normaliza (quita el `@` inicial, ignora mayúsculas).
* `whatsapp_user_id` — BSUID del contacto (identidad opaca de Meta). Igualdad exacta, sin normalizar.
* `uuid` — UUID interno de 1TO1 AI, si ya lo tienes guardado.
* `channel` — clave pública del canal (**obligatorio** en todo request). Lístalas con `GET /channels`. No distingue mayúsculas/minúsculas. Fija el canal objetivo; en las vías por contacto restringe la resolución a ese canal, y con `uuid` el resolver lo ignora pero el contrato igual lo exige.

Exactamente **uno** de `phone`, `username`, `whatsapp_user_id` o `uuid` debe venir: cero o dos identificadores responden `400` (`INVALID_REQUEST`).

### Respuesta

```json theme={null}
{
  "conversation_info": {
    "phone": "5215512345678",
    "window_open": true,
    "window_expires_at": "2026-07-21T18:30:00Z",
    "inbox_status": "pending",
    "is_tester": false,
    "mailbox": { "name": "Ventas" },
    "ai_employee": { "name": "Aura" },
    "tags": [{ "name": "VIP" }]
  },
  "contact_info": {
    "first_name": "Juan",
    "middle_name": "Carlos",
    "last_name": "Pérez",
    "second_last_name": "López",
    "full_name": "Juan Carlos Pérez López",
    "username": "juanp",
    "phone": "5215512345678",
    "whatsapp_user_id": "5215512345678"
  }
}
```

`window_open` es el campo que decide qué puedes enviar: si es `false`, el único mensaje permitido es una plantilla aprobada. `window_expires_at` viene en `null` cuando el contacto nunca escribió (la ventana nunca se abrió), e `inbox_status` es `pending` o `resolved`. `mailbox` y `ai_employee` son `null` cuando la conversación no tiene buzón o empleado AI asignado. `is_tester` marca si la conversación se creó desde el módulo de pruebas.

<Note>
  En `contact_info`, `whatsapp_user_id` devuelve el BSUID real cuando existe, con fallback al teléfono mientras Meta no migre. Si el valor que recibes es el teléfono, reenvíalo como `phone` y no como `whatsapp_user_id` — el resolver matchea BSUIDs por igualdad exacta y daría `404`.
</Note>

**Errores**

* `400` `INVALID_REQUEST` — la referencia trae cero o dos identificadores, o falta `channel`.
* `404` `CONVERSATION_NOT_FOUND` — la conversación no existe o pertenece a otro negocio. `CHANNEL_NOT_FOUND` — la clave de canal no existe.
* `409` `PHONE_NUMBER_AMBIGUOUS` / `USERNAME_AMBIGUOUS` — varios contactos comparten ese teléfono o ese username. Identifica por `whatsapp_user_id` o `uuid`.

### Ejemplo

Una lectura pura: consulta el estado y no cambia nada de la conversación.

```bash theme={null}
curl -X GET "https://app.1to1.ai/api/v1/public/{slug}/conversation?phone=5215512345678&channel=ch_7A9K2M4Q" \
  -H "Authorization: Bearer sk_1to1_tu_api_key"
```

Si la respuesta trae `"window_open": false`, la acción que corresponde es enviar una plantilla; si trae `true`, puedes mandar texto, media o una respuesta rápida.

## Hilo de mensajes y eventos

```http theme={null}
GET /conversation/messages
```

Devuelve los mensajes y los eventos del historial. Se identifica con la misma referencia, así que **no hace falta conocer ningún uuid**.

**Parámetros**

* `phone` / `username` / `whatsapp_user_id` / `uuid` — la referencia de la conversación, con la misma regla: exactamente uno.
* `channel` — clave pública del canal (**obligatorio**).
* `cursor` — cursor opaco devuelto por la página anterior en `next_cursor` (hasta 512 caracteres). No reutilices cursores entre endpoints distintos.
* `limit` — items por página. Por defecto 50, máximo 100.

<Note>
  El hilo se pagina **hacia atrás en el tiempo**: la primera llamada trae los items más recientes y `next_cursor` avanza hacia los más antiguos. `has_more` en `true` significa que quedan items **más antiguos** por leer. El orden dentro de la página es cronológico y no es configurable (no hay parámetro `order`).
</Note>

### Respuesta

```json theme={null}
{
  "items": [
    {
      "type": "message",
      "direction": "contact",
      "event": "message_received",
      "content_type": "text",
      "body": "Hola, ¿tienen disponible el paquete premium?",
      "author": { "type": "customer", "name": "Ana Pérez" },
      "status": "delivered",
      "sent_at": "2026-07-02T14:39:00.000Z"
    },
    {
      "type": "message",
      "direction": "business",
      "event": "message_sent",
      "content_type": "text",
      "body": "¡Buen día! Sí, el paquete premium está disponible.",
      "author": { "type": "ai_employee", "name": "Ventas nocturnas" },
      "status": "read",
      "sent_at": "2026-07-02T14:39:12.000Z"
    },
    {
      "type": "event",
      "direction": "business",
      "event": "context_note",
      "content_type": null,
      "body": "Cliente pidió cotización formal por correo.",
      "author": { "type": "api_token", "name": "CRM externo" },
      "status": null,
      "sent_at": "2026-07-02T15:02:00.000Z"
    }
  ],
  "next_cursor": "MjAyNi0wNy0wMlQxNDozOTowMC4wMDBafDkxODIz",
  "has_more": true
}
```

Cada item responde cuatro preguntas: quién habló (`direction` y `author`), qué pasó (`event`), con qué contenido (`content_type` y `body`) y cuándo (`sent_at`).

* `type` — `message` o `event`. Discrimina la unión: los SDKs auto-generados lo exponen como tagged union.
* `direction` — `contact` (lo envió la persona del otro lado) o `business` (salió de tu negocio).
* `author.type` — `customer`, `human`, `ai_employee`, `api_token`, `mass_campaign` o `system`. `author.name` puede ser `null`.
* `event` — en los `message`: `message_received` o `message_sent`. En los `event`: `context_note`, `contact_name_updated`, `contact_phone_updated`, `contact_email_updated`, `scheduled_cancel` o `conversion`.
* `content_type` — en los `message`: `text`, `image`, `audio`, `video`, `document`, `location`, `sticker`, `contacts`, `template`, `interactive` o `reaction`. Siempre `null` en los `event`.
* `status` — en los `message`: `pending`, `sent`, `delivered`, `read` o `failed`. Siempre `null` en los `event`.
* `sent_at` — reloj de negocio del item y clave de orden del hilo. Siempre presente.

**Errores**

* `400` `INVALID_REQUEST` — referencia inválida. `INVALID_CURSOR` — cursor corrupto o no emitido por este endpoint.
* `404` `CONVERSATION_NOT_FOUND` / `CHANNEL_NOT_FOUND`.
* `409` `PHONE_NUMBER_AMBIGUOUS` / `USERNAME_AMBIGUOUS`.

### Ejemplo

También es una lectura: recorrer el hilo completo no altera la conversación ni marca nada como leído.

```bash theme={null}
curl -X GET "https://app.1to1.ai/api/v1/public/{slug}/conversation/messages?phone=5215512345678&channel=ch_7A9K2M4Q&limit=50" \
  -H "Authorization: Bearer sk_1to1_tu_api_key"
```

Página siguiente (items más antiguos), con el `next_cursor` de la respuesta anterior:

```bash theme={null}
curl -X GET "https://app.1to1.ai/api/v1/public/{slug}/conversation/messages?phone=5215512345678&channel=ch_7A9K2M4Q&cursor=MjAyNi0wNy0wMlQxNDozOTowMC4wMDBafDkxODIz" \
  -H "Authorization: Bearer sk_1to1_tu_api_key"
```

Con el estado y el historial en mano, la escritura va por las acciones: [Enviar mensaje](/es/action-groups/send-message) para responder y [Cambiar estado de la conversación](/es/action-groups/conversation-status) para marcarla como resuelta o pendiente. El contexto completo de la referencia y de la ventana de 24h está en [Conversaciones](/es/conversations).