> ## 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.

# Livia - Asistente 360

> Livia - Asistente 360 es tu asistente dentro de ZappWay: conversa, automatiza tareas recurrentes mediante rutinas, muestra oportunidades comerciales y mantiene un registro de auditoría completo de todo lo que hace.

> **Lo que aprenderás:**
> Esta página cubre todas las funciones de Livia: conversaciones de chat, rutinas automatizadas, aprobaciones de acciones, oportunidades comerciales, controles de privacidad, seguimiento de uso y diagnósticos de integración.

***

## 🔢 Tabla de contenidos

1. [Overview](#1-overview)
2. [Prerequisites](#2-prerequisites)
3. [Endpoint Reference](#3-endpoint-reference)
4. [Chat](#4-chat)
5. [Conversations](#5-conversations)
6. [Routines](#6-routines)
7. [Approvals](#7-approvals)
8. [Opportunities](#8-opportunities)
9. [State & Capabilities](#9-state--capabilities)
10. [Privacy & Retention](#10-privacy--retention)
11. [Audit Log](#11-audit-log)
12. [Settings & Usage](#12-settings--usage)
13. [Integration Diagnostics](#13-integration-diagnostics)
14. [Error Handling](#14-error-handling)
15. [Best Practices](#15-best-practices)

***

## 1. Descripción general

### ¿Qué es Livia - Asistente 360?

**Livia - Asistente 360** es un asistente de IA basado en planes integrado directamente en ZappWay. A diferencia de los empleados de IA (que manejan las conversaciones con clientes externos), Livia trabaja **para usted y su equipo** internamente.

**Capacidades clave:**

* 💬 **Chat en lenguaje natural** con historial de conversaciones completo
* 🔄 **Rutinas automatizadas**: tareas recurrentes que se ejecutan según lo programado
* ✅ **Aprobaciones de acciones**: revise las acciones propuestas por la IA antes de ejecutarlas
* 📈 **Oportunidades de negocio**: información valiosa obtenida mediante IA a partir de sus datos
* 🔒 **Controles de privacidad**: gestión completa de la retención de datos
* 📋 **Registro de auditoría**: historial completo de cada acción que realizó el asistente

### Requisito del plan

Livia está disponible solo en planes que incluyen la marca de función `personal_assistant`. Al intentar acceder a cualquier punto final sin el plan requerido, se devuelve:

```json theme={null}
{ "error": "Livia - 360 Assistant requires a PRO plan." }
```

***

## 2. Requisitos previos

* Cuenta activa de ZappWay con un plan que incluye Livia
* Sesión autenticada (Livia siempre está vinculada al usuario, no a la organización a nivel de chat)
* Al menos una integración configurada para funcionalidad completa (opcional para chat básico)

***

## 3. Referencia de punto final

| Método             | Punto final                                                              | Descripción                               | Autenticación                |
| ------------------ | ------------------------------------------------------------------------ | ----------------------------------------- | ---------------------------- |
| `POST`             | `/api/personal-assistant/chat`                                           | Enviar un mensaje (streaming SSE o JSON)  | `personal_assistant.execute` |
| `GET`              | `/api/personal-assistant/state`                                          | Obtener estado y contexto del asistente   | `personal_assistant.read`    |
| `GET`              | `/api/personal-assistant/capabilities`                                   | Listar capacidades del asistente          | `personal_assistant.read`    |
| `PATCH`            | `/api/personal-assistant/settings`                                       | Actualizar la configuración del asistente | `personal_assistant.manage`  |
| `GET`              | `/api/personal-assistant/usage`                                          | Obtener estadísticas de uso               | `personal_assistant.read`    |
| `POST`             | `/api/personal-assistant/feedback`                                       | Enviar comentarios sobre una respuesta    | `personal_assistant.execute` |
| `POST`             | `/api/personal-assistant/context-help`                                   | Obtenga ayuda contextual                  | `personal_assistant.read`    |
| **Conversaciones** |                                                                          |                                           |                              |
| `GET`              | `/api/personal-assistant/conversations`                                  | Listar conversaciones                     | `personal_assistant.execute` |
| `POST`             | `/api/personal-assistant/conversations`                                  | Crear una conversación                    | `personal_assistant.execute` |
| `PATCH`            | `/api/personal-assistant/conversations/[id]`                             | Actualizar conversación                   | `personal_assistant.execute` |
| `DELETE`           | `/api/personal-assistant/conversations/[id]`                             | Eliminar conversación                     | `personal_assistant.execute` |
| `GET`              | `/api/personal-assistant/conversations/[id]/messages`                    | Listar mensajes en conversación           | `personal_assistant.read`    |
| `POST`             | `/api/personal-assistant/conversations/[id]/messages/[messageId]/cancel` | Cancelar un mensaje en streaming          | `personal_assistant.execute` |
| `POST`             | `/api/personal-assistant/conversations/[id]/messages/[messageId]/retry`  | Reintentar un mensaje fallido             | `personal_assistant.execute` |
| **Rutinas**        |                                                                          |                                           |                              |
| `GET`              | `/api/personal-assistant/routines`                                       | Lista de rutinas                          | `personal_assistant.read`    |
| `POST`             | `/api/personal-assistant/routines`                                       | Crear/actualizar una rutina               | `personal_assistant.manage`  |
| `GET`              | `/api/personal-assistant/routines/[id]`                                  | Consigue una rutina específica            | `personal_assistant.manage`  |
| `PATCH`            | `/api/personal-assistant/routines/[id]`                                  | Actualizar una rutina                     | `personal_assistant.manage`  |
| `DELETE`           | `/api/personal-assistant/routines/[id]`                                  | Eliminar una rutina                       | `personal_assistant.manage`  |
| `POST`             | `/api/personal-assistant/routines/[id]/toggle`                           | Activar/desactivar una rutina             | `personal_assistant.manage`  |
| `GET`              | `/api/personal-assistant/routines/[id]/executions`                       | Obtener historial de ejecución de rutina  | `personal_assistant.read`    |
| `POST`             | `/api/personal-assistant/routines/run`                                   | Activar manualmente una rutina            | `personal_assistant.execute` |
| **Aprobaciones**   |                                                                          |                                           |                              |
| `GET`              | `/api/personal-assistant/approvals`                                      | Listado de aprobaciones pendientes        | `personal_assistant.read`    |
| `POST`             | `/api/personal-assistant/actions/[id]/approve`                           | Aprobar una acción                        | `personal_assistant.execute` |
| `POST`             | `/api/personal-assistant/actions/[id]/reject`                            | Rechazar una acción                       | `personal_assistant.execute` |
| **Oportunidades**  |                                                                          |                                           |                              |
| `GET`              | `/api/personal-assistant/opportunities`                                  | Listar oportunidades                      | `personal_assistant.read`    |
| `PATCH`            | `/api/personal-assistant/opportunities/[id]`                             | Actualizar el estado de la oportunidad    | `personal_assistant.manage`  |
| **Privacidad**     |                                                                          |                                           |                              |
| `GET`              | `/api/personal-assistant/privacy`                                        | Obtener configuración de privacidad       | `personal_assistant.manage`  |
| `DELETE`           | `/api/personal-assistant/privacy`                                        | Eliminar todos los datos personales       | `personal_assistant.manage`  |
| `GET`              | `/api/personal-assistant/privacy/retention`                              | Obtener política de retención             | `personal_assistant.manage`  |
| `PATCH`            | `/api/personal-assistant/privacy/retention`                              | Actualizar política de retención          | `personal_assistant.manage`  |
| **Auditoría**      |                                                                          |                                           |                              |
| `GET`              | `/api/personal-assistant/audit`                                          | Obtener registro de auditoría             | `personal_assistant.audit`   |
| `GET`              | `/api/personal-assistant/audit/export`                                   | Exportar registro de auditoría            | `personal_assistant.audit`   |
| **Diagnóstico**    |                                                                          |                                           |                              |
| `GET`              | `/api/personal-assistant/integrations/[integration]/diagnostics`         | Ejecutar diagnóstico de integración       | `personal_assistant.manage`  |

***

## 4. Charla

### Enviar un mensaje

El punto final del chat es el núcleo de Livia. Acepta un mensaje y devuelve una respuesta **transmisión de eventos enviados por el servidor (SSE)** o una respuesta **JSON estándar**.

```bash theme={null}
POST /api/personal-assistant/chat
Content-Type: application/json
```

**Cuerpo de la solicitud:**

| Campo            | Tipo      | Requerido | Descripción                                 |
| ---------------- | --------- | --------- | ------------------------------------------- |
| `message`        | `string`  | ✅         | El mensaje del usuario                      |
| `conversationId` | `string`  | ❌         | Continuar una conversación existente        |
| `stream`         | `boolean` | ❌         | Devolver flujo SSE. Predeterminado: `false` |

**Ejemplo (sin transmisión):**
***CÓDIGO\_BLOQUE\_2***

**Ejemplo (transmisión):**
***CÓDIGO\_BLOQUE\_3***

### Formato de respuesta de transmisión (SSE)

Cuando `stream: true`, el punto final devuelve `Content-Type: text/event-stream`.

**Eventos:**

| Evento  | Datos                                          | Descripción                    |
| ------- | ---------------------------------------------- | ------------------------------ |
| `chunk` | `{ "delta": "partial text" }`                  | Fragmento de texto incremental |
| `done`  | Objeto de resultado completo                   | Respuesta final con metadatos  |
| `error` | `{ "code": "CHAT_FAILED", "retryable": true }` | Se produjo un error            |

**Heartbeat:** Se envía un comentario `: heartbeat` cada 15 segundos para mantener viva la conexión.

**Tiempo de espera:** Las transmisiones se cierran automáticamente después de 90 segundos.

**TypeScript (transmisión):**
***CÓDIGO\_BLOQUE\_4***

**Limitación de tarifas:** El punto final del chat aplica límites de tarifas basados ​​en el plan. Los encabezados de límite de tasa se incluyen en cada respuesta:

* `X-RateLimit-Limit`
* `X-RateLimit-Remaining`
* `X-RateLimit-Reset`

***

## 5. Conversaciones

Livia mantiene un **historial de conversaciones persistente**. Cada conversación es un hilo de mensajes.

### Listar conversaciones

```bash theme={null}
GET /api/personal-assistant/conversations
```

Devuelve todas las conversaciones del usuario autenticado, ordenadas por última actividad.

### Crear una conversación

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

### Recibir mensajes en una conversación

```bash theme={null}
GET /api/personal-assistant/conversations/{conversationId}/messages
```

### Cancelar un mensaje en streaming

Si hay una respuesta de transmisión en curso y desea detenerla:

```bash theme={null}
POST /api/personal-assistant/conversations/{conversationId}/messages/{messageId}/cancel
```

### Reintentar un mensaje fallido

```bash theme={null}
POST /api/personal-assistant/conversations/{conversationId}/messages/{messageId}/retry
```

***

## 6. Rutinas

**Rutinas** son tareas automatizadas que se ejecutan según una programación. Livia puede ejecutar rutinas de forma automática o bajo demanda.

### Lista de rutinas

```bash theme={null}
GET /api/personal-assistant/routines
```

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

### Crear/actualizar una rutina

```bash theme={null}
POST /api/personal-assistant/routines
Content-Type: application/json
```

### Alternar una rutina

Habilite o deshabilite una rutina sin eliminarla:

```bash theme={null}
POST /api/personal-assistant/routines/{routineId}/toggle
```

### Obtener historial de ejecución

```bash theme={null}
GET /api/personal-assistant/routines/{routineId}/executions
```

Devuelve las últimas N ejecuciones de una rutina, incluido el estado (éxito/fallido) y la salida.

### Ejecutar una rutina manualmente

```bash theme={null}
POST /api/personal-assistant/routines/run
Content-Type: application/json
```

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

***

## 7. Aprobaciones

Algunas acciones propuestas por Livia requieren su **aprobación explícita** antes de su ejecución. El sistema de aprobaciones le brinda control total sobre las acciones automatizadas.

### Lista de aprobaciones pendientes

```bash theme={null}
GET /api/personal-assistant/approvals
```

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

### Aprobar una acción

```bash theme={null}
POST /api/personal-assistant/actions/{approvalId}/approve
```

La acción se ejecuta inmediatamente después de la aprobación.

### Rechazar una acción

```bash theme={null}
POST /api/personal-assistant/actions/{approvalId}/reject
```

La acción queda descartada. Opcionalmente, puede proporcionar un motivo.

***

## 8. Oportunidades

Livia muestra **oportunidades de negocio**: información identificada por IA a partir de los datos de sus conversaciones, contactos e integraciones.

### Listar oportunidades

```bash theme={null}
GET /api/personal-assistant/opportunities
```

### Actualizar una oportunidad

Marcar una oportunidad como activada, descartada o en curso:

```bash theme={null}
PATCH /api/personal-assistant/opportunities/{opportunityId}
Content-Type: application/json
```

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

***

## 9. Estado y capacidades

### Obtener estado de asistente

Devuelve el estado actual de Livia, incluido el contexto, el estado de las integraciones y las funciones activas.

```bash theme={null}
GET /api/personal-assistant/state
```

### Obtener capacidades

Devuelve la lista de acciones y funciones disponibles para el asistente según su plan y las integraciones configuradas.

```bash theme={null}
GET /api/personal-assistant/capabilities
```

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

***

## 10. Privacidad y retención

Tienes control total sobre los datos que almacena Livia.

### Obtener configuración de privacidad

```bash theme={null}
GET /api/personal-assistant/privacy
```

### Eliminar todos los datos personales

Elimina permanentemente todo el historial de conversaciones, datos de rutina y contexto personal almacenados por el asistente.

```bash theme={null}
DELETE /api/personal-assistant/privacy
```

> ⚠️ **Esta acción es irreversible.** Todo el historial de conversaciones y los datos personales se eliminarán permanentemente.

### Obtener política de retención

```bash theme={null}
GET /api/personal-assistant/privacy/retention
```

### Actualizar política de retención

```bash theme={null}
PATCH /api/personal-assistant/privacy/retention
Content-Type: application/json
```

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

***

## 11. Registro de auditoría

Cada acción que realiza Livia se registra para responsabilidad y revisión.

### Obtener registro de auditoría

```bash theme={null}
GET /api/personal-assistant/audit
```

Admite paginación y filtrado de fechas mediante parámetros de consulta.

### Exportar registro de auditoría

Descargue el registro de auditoría completo como archivo:

```bash theme={null}
GET /api/personal-assistant/audit/export
```

La respuesta es un archivo descargable (formato CSV o JSON, según la implementación).

***

## 12. Configuración y uso

### Actualizar configuración

Configurar el comportamiento de Livia:

```bash theme={null}
PATCH /api/personal-assistant/settings
Content-Type: application/json
```

### Obtener uso

Vea las estadísticas de uso de Livia (recuento de mensajes, ejecuciones de rutina, etc.):

```bash theme={null}
GET /api/personal-assistant/usage
```

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

***

## 13. Diagnóstico de integración

Ejecute diagnósticos en una integración específica para verificar la conectividad y los permisos:

```bash theme={null}
GET /api/personal-assistant/integrations/{integration}/diagnostics
```

**Parámetros de ruta:**

| Parámetro     | Tipo     | Descripción                                                              |
| ------------- | -------- | ------------------------------------------------------------------------ |
| `integration` | `string` | Identificador de integración (por ejemplo, `gmail`, `slack`, `calendar`) |

***

## 14. Manejo de errores

| Error                                       | Causa                                       | Cómo solucionarlo                                           |
| ------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------- |
| `Livia - 360 Assistant requires a PRO plan` | El plan no incluye Livia                    | Actualiza tu plan                                           |
| `Rate limit exceeded`                       | Demasiadas solicitudes de chat              | Espere a que se restablezca la ventana de límite de tasa    |
| `REQUEST_CANCELED`                          | Cliente desconectado durante la transmisión | El usuario canceló: no es necesario realizar ninguna acción |
| `CHAT_FAILED`                               | Error interno durante el chat               | Reintentar la solicitud                                     |
| `Routine not found`                         | ID de rutina no válido                      | Verifique que exista el ID de la rutina                     |
| `Approval not found`                        | ID de aprobación no válido o ya resuelto    | Verificar si la aprobación ya fue accionada                 |

### Códigos de estado

| Estado | Significado                                   |
| ------ | --------------------------------------------- |
| `200`  | Solicitud exitosa                             |
| `201`  | Recurso creado                                |
| `400`  | Cuerpo de solicitud no válido                 |
| `401`  | No autenticado                                |
| `403`  | Permisos insuficientes o restricción del plan |
| `404`  | Recurso no encontrado                         |
| `429`  | Límite de tarifa excedido                     |
| `500`  | Error interno del servidor                    |

***

## 15. Mejores prácticas

### Chat en tiempo real

* Siempre implemente el manejo de desconexión del lado del cliente para llamar al punto final **cancelar** si el usuario se aleja
* Mostrar un indicador de carga mientras se espera el primer evento `chunk`
* Muestra el texto progresivamente a medida que llegan los eventos `chunk` para una mejor experiencia de usuario.

### Rutinas

* Comience con rutinas simples (por ejemplo, resúmenes diarios) antes de automatizaciones complejas de varios pasos
* Utilice el **historial de ejecución** para verificar que las rutinas se estén ejecutando correctamente antes de habilitar otras nuevas.
* Configure rutinas para que se ejecuten durante las horas de menor actividad (temprano en la mañana) para evitar competir con el uso interactivo.

### Aprobaciones

* Verifique las aprobaciones pendientes con regularidad: las acciones urgentes pueden caducar
* Revisar atentamente la acción `payload` antes de aprobarla, especialmente para acciones que envían comunicaciones externas.
* Utilice el punto final `reject` para proporcionar comentarios que ayuden al asistente a conocer sus preferencias

### Privacidad

* Establezca una política de retención que coincida con los requisitos de gobierno de datos de su organización.
* Exportar el registro de auditoría periódicamente para registros de cumplimiento.
* Utilice `DELETE /privacy` como parte de los flujos de trabajo de baja para los miembros del equipo que salen