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

# Conversaciones

> Las conversaciones son el núcleo de ZappWay: cada mensaje intercambiado con un contacto a través de cualquier canal (WhatsApp, correo electrónico, widget, TikTok y más) se organiza como una conversación.

> **Lo que aprenderás:**
> Esta página explica cómo funcionan las conversaciones en ZappWay, cómo enumerarlas y administrarlas, cómo actualizar su estado de forma masiva, cómo exportarlas y cómo usar la función de resumen de IA.

***

## 🔢 Tabla de contenidos

1. [Overview](#1-overview)
2. [Endpoint Reference](#2-endpoint-reference)
3. [Listing Conversations](#3-listing-conversations)
4. [Managing a Conversation](#4-managing-a-conversation)
5. [Bulk Status Update](#5-bulk-status-update)
6. [Export Conversations](#6-export-conversations)
7. [Evaluating Answers](#7-evaluating-answers)
8. [Response Format](#8-response-format)
9. [Best Practices](#9-best-practices)
10. [Troubleshooting](#10-troubleshooting)

***

## 1. Descripción general

### ¿Qué es una conversación?

Una **Conversación** en ZappWay es un hilo completo de mensajes entre un contacto y su organización, mediado por un empleado de IA, un agente humano o ambos.

**Las conversaciones pueden originarse en:**

* 💬 WhatsApp (API empresarial)
* 📧 Bandeja de entrada de correo electrónico
* 🌐 Widget (chat del sitio web)
* 📱 DM de TikTok
* 🔌 Cualquier integración conectada

**Cada conversación tiene:**

* Un **contacto**: con quién es la conversación.
* Un **canal**: donde se desarrolla la conversación.
* Un **estado**: `open`, `resolved` o `snoozed`
* Una asignación de **Empleado AI** (opcional)
* Un **hilo de mensajes** completo con marcas de tiempo

### IA y colaboración humana

Las conversaciones admiten un **modelo híbrido**: el empleado de IA puede manejar los mensajes automáticamente y un agente humano puede hacerse cargo en cualquier momento. Los mensajes de la IA y los mensajes humanos aparecen en el mismo hilo.

***

## 2. Referencia de punto final

| Método   | Punto final                                       | Descripción                                                 | Autenticación                               |
| -------- | ------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------- |
| `GET`    | `/api/conversations`                              | Listar conversaciones con filtros                           | Autenticación opcional (soporte de widgets) |
| `HEAD`   | `/api/conversations`                              | Comprobación previa de CORS                                 | Ninguno                                     |
| `GET`    | `/api/conversations/[conversationId]`             | Obtener una conversación específica                         | Sesión de organización                      |
| `PATCH`  | `/api/conversations/[conversationId]`             | Actualizar conversación (asignar agente, establecer estado) | Sesión de organización                      |
| `DELETE` | `/api/conversations/[conversationId]`             | Eliminar una conversación                                   | Sesión de organización                      |
| `POST`   | `/api/conversations/update-status`                | Actualización masiva de estados de conversación             | Sesión de organización                      |
| `POST`   | `/api/conversations/bulk-unread`                  | Marcar conversaciones como no leídas de forma masiva        | Sesión de organización                      |
| `GET`    | `/api/conversations/export`                       | Exportar conversaciones a un archivo                        | Sesión de organización                      |
| `POST`   | `/api/conversations/[conversationId]/eval-answer` | Evaluar la calidad de las respuestas de la IA               | Sesión de organización                      |

***

## 3. Listado de conversaciones

### Listar conversaciones

```bash theme={null}
GET /api/conversations
```

Admite **autenticación opcional**: las solicitudes autenticadas devuelven conversaciones de la organización; Las solicitudes no autenticadas pueden devolver conversaciones de widgets públicos.

**Parámetros de consulta:**

| Parámetro   | Tipo                                | Descripción                                                    |
| ----------- | ----------------------------------- | -------------------------------------------------------------- |
| `status`    | `"open" \| "resolved" \| "snoozed"` | Filtrar por estado de conversación                             |
| `agentId`   | `string`                            | Filtrar por empleado de IA asignado                            |
| `contactId` | `string`                            | Filtrar por contacto                                           |
| `channel`   | `string`                            | Filtrar por canal (por ejemplo, `whatsapp`, `email`, `widget`) |
| `page`      | `number`                            | Número de página para paginación                               |
| `limit`     | `number`                            | Número de resultados por página                                |
| `search`    | `string`                            | Búsqueda de texto completo en el contenido de la conversación  |
| `dateFrom`  | `ISO 8601`                          | Filtrar conversaciones después de esta fecha                   |
| `dateTo`    | `ISO 8601`                          | Filtrar conversaciones anteriores a esta fecha                 |

**Ejemplo:**
***CÓDIGO\_BLOQUE\_1***

**Respuesta:**
***CÓDIGO\_BLOQUE\_2***

**rizo:**
***CÓDIGO\_BLOQUE\_3***

**Mecanografiado:**
***CÓDIGO\_BLOQUE\_4***

***

## 4. Gestionar una conversación

### Obtener una conversación

```bash theme={null}
GET /api/conversations/{conversationId}
```

Devuelve el objeto de conversación completo, incluidos todos los mensajes y detalles de contacto.

### Actualizar una conversación

```bash theme={null}
PATCH /api/conversations/{conversationId}
Content-Type: application/json
```

**Cuerpo de la solicitud:**

| Campo            | Tipo                                | Descripción                             |
| ---------------- | ----------------------------------- | --------------------------------------- |
| `status`         | `"open" \| "resolved" \| "snoozed"` | Actualizar el estado de la conversación |
| `agentId`        | `string \| null`                    | Asignar o desasignar un empleado de IA  |
| `assignedUserId` | `string \| null`                    | Asignar a un miembro del equipo humano  |
| `note`           | `string`                            | Añadir una nota interna                 |
| `snoozeUntil`    | `ISO 8601`                          | Posponer hasta una fecha específica     |

**Ejemplo: resolver una conversación:**
***CÓDIGO\_BLOQUE\_7***

**Ejemplo: Asignar a un empleado de IA:**
***CÓDIGO\_BLOQUE\_8***

**Ejemplo: Posponer:**
***CÓDIGO\_BLOQUE\_9***

### Eliminar una conversación

```bash theme={null}
DELETE /api/conversations/{conversationId}
```

> ⚠️ Al eliminar una conversación se eliminan permanentemente todos los mensajes asociados. Esta acción es irreversible.

***

## 5. Actualización de estado masiva

Actualiza el estado de varias conversaciones a la vez.

```bash theme={null}
POST /api/conversations/update-status
Content-Type: application/json
```

**Cuerpo de la solicitud:**

| Campo             | Tipo                                | Requerido | Descripción                                              |
| ----------------- | ----------------------------------- | --------- | -------------------------------------------------------- |
| `conversationIds` | `string[]`                          | ✅         | Conjunto de ID de conversación para actualizar           |
| `status`          | `"open" \| "resolved" \| "snoozed"` | ✅         | Nuevo estado para todas las conversaciones especificadas |

**Ejemplo: resolver varias conversaciones:**
***CÓDIGO\_BLOQUE\_12***

**rizo:**
***CÓDIGO\_BLOQUE\_13***

### Marcar como no leído en masa

```bash theme={null}
POST /api/conversations/bulk-unread
Content-Type: application/json
```

**Cuerpo de la solicitud:**
***CÓDIGO\_BLOQUE\_15***

***

## 6. Exportar conversaciones

Descargue conversaciones como un archivo para informes, cumplimiento o análisis.

```bash theme={null}
GET /api/conversations/export
```

**Parámetros de consulta:**

| Parámetro  | Tipo              | Descripción                                    |
| ---------- | ----------------- | ---------------------------------------------- |
| `status`   | `string`          | Filtrar por estado antes de exportar           |
| `dateFrom` | `ISO 8601`        | Exportar conversaciones desde esta fecha       |
| `dateTo`   | `ISO 8601`        | Exportar conversaciones hasta esta fecha       |
| `format`   | `"csv" \| "json"` | Formato de exportación (predeterminado: `csv`) |

**Ejemplo:**
***CÓDIGO\_BLOQUE\_17***

La respuesta contiene el archivo como un archivo adjunto descargable.

***

## 7. Evaluación de respuestas

Utilice el punto final de evaluación para calificar la calidad de las respuestas generadas por IA. Esta retroalimentación se utiliza para mejorar el rendimiento de la IA con el tiempo.

```bash theme={null}
POST /api/conversations/{conversationId}/eval-answer
Content-Type: application/json
```

**Cuerpo de la solicitud:**

| Campo       | Tipo                       | Requerido | Descripción                       |
| ----------- | -------------------------- | --------- | --------------------------------- |
| `messageId` | `string`                   | ✅         | El ID del mensaje de IA a evaluar |
| `rating`    | `"positive" \| "negative"` | ✅         | Su calificación de calidad        |
| `feedback`  | `string`                   | ❌         | Comentarios escritos opcionales   |

**Ejemplo:**
***CÓDIGO\_BLOQUE\_19***

***

## 8. Formato de respuesta

### Objeto de conversación

| Campo                | Tipo             | Descripción                                  |
| -------------------- | ---------------- | -------------------------------------------- |
| `id`                 | `string`         | ID de conversación única                     |
| `contactId`          | `string`         | ID del contacto                              |
| `contact`            | `Contact`        | Objeto de contacto completo                  |
| `channel`            | `string`         | Canal de origen                              |
| `status`             | `string`         | Estado actual: `open`, `resolved`, `snoozed` |
| `agentId`            | `string \| null` | ID de empleado de IA asignado                |
| `assignedUserId`     | `string \| null` | ID de usuario humano asignado                |
| `lastMessageAt`      | `ISO 8601`       | Marca de tiempo del último mensaje           |
| `lastMessagePreview` | `string`         | Vista previa del último mensaje              |
| `unreadCount`        | `number`         | Número de mensajes no leídos                 |
| `createdAt`          | `ISO 8601`       | Cuando se creó la conversación               |

### Códigos de estado

| Estado | Significado                                 |
| ------ | ------------------------------------------- |
| `200`  | Solicitud exitosa                           |
| `204`  | Eliminado con éxito                         |
| `400`  | Cuerpo o parámetros de solicitud no válidos |
| `401`  | No autenticado                              |
| `403`  | Permisos insuficientes                      |
| `404`  | Conversación no encontrada                  |
| `500`  | Error interno del servidor                  |

***

## 9. Mejores prácticas

### Gestión de estado

| Estado     | Usar cuando                                                                                |
| ---------- | ------------------------------------------------------------------------------------------ |
| `open`     | La conversación es activa y requiere atención                                              |
| `resolved` | El problema se ha solucionado por completo: la conversación ha finalizado                  |
| `snoozed`  | La conversación necesita seguimiento más tarde: se reabre automáticamente en `snoozeUntil` |

**Consejos:**

* Utilice **actualización de estado masiva** para la gestión de colas al final del día
* Establezca `snoozeUntil` para el siguiente día hábil para conversaciones de baja prioridad
* Resuelva las conversaciones con prontitud para mantener su cola limpia

### Filtrado y búsqueda

* Combine filtros (por ejemplo, `status=open&channel=whatsapp&agentId=agent_123`) para obtener resultados precisos
* Utilice `search` para buscar palabras clave cuando recuerde el contenido de la conversación pero no el contacto.
* Exportar subconjuntos filtrados para necesidades de informes específicas.

### Evaluación de respuestas de IA

* Califique las respuestas de IA con regularidad para mejorar el rendimiento del modelo.
* Proporcione `feedback` escrito para calificaciones negativas; esto ayuda a identificar patrones
* Centrarse en calificar las respuestas en las que la IA cometió un error factual o no cumplió con la intención.

***

## 10. Solución de problemas

| Problema                                             | Posible causa                                                | Solución                                                                       |
| ---------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| La conversación no aparece en la lista               | Se aplicó un filtro incorrecto                               | Intente eliminar filtros y buscar por contacto o palabra clave                 |
| La actualización de estado masiva falla parcialmente | Algunas identificaciones no pertenecen a su organización     | Verifique que todos los ID de conversación sean correctos y de su organización |
| La exportación devuelve un archivo vacío             | Ninguna conversación coincide con el filtro de fecha/estado  | Ampliar el rango de fechas o eliminar el filtro de estado                      |
| No se puede eliminar una conversación                | La conversación está vinculada a una sesión de widget activa | Espere a que finalice la sesión o comuníquese con el soporte                   |
| Evaluación de respuesta de IA rechazada              | `messageId` no es un mensaje generado por IA                 | Solo se pueden evaluar mensajes generados por IA                               |