Livia - Asistente 360 - ZappWay - Connect custom data to large language models

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.

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:

{ "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.

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

GET /api/personal-assistant/conversations

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

Crear una conversación

POST /api/personal-assistant/conversations
Content-Type: application/json

Recibir mensajes en una conversación

GET /api/personal-assistant/conversations/{conversationId}/messages

Cancelar un mensaje en streaming

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

POST /api/personal-assistant/conversations/{conversationId}/messages/{messageId}/cancel

Reintentar un mensaje fallido

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

GET /api/personal-assistant/routines

Respuesta: CÓDIGO_BLOQUE_11

Crear/actualizar una rutina

POST /api/personal-assistant/routines
Content-Type: application/json

Alternar una rutina

Habilite o deshabilite una rutina sin eliminarla:

POST /api/personal-assistant/routines/{routineId}/toggle

Obtener historial de ejecución

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

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

GET /api/personal-assistant/approvals

Respuesta: CÓDIGO_BLOQUE_18

Aprobar una acción

POST /api/personal-assistant/actions/{approvalId}/approve

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

Rechazar una acción

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

GET /api/personal-assistant/opportunities

Actualizar una oportunidad

Marcar una oportunidad como activada, descartada o en curso:

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.

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.

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

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.

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

GET /api/personal-assistant/privacy/retention

Actualizar política de retención

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

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:

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:

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.):

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:

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

​🔢 Tabla de contenidos

​1. Descripción general

​¿Qué es Livia - Asistente 360?

​Requisito del plan

​2. Requisitos previos

​3. Referencia de punto final

​4. Charla

​Enviar un mensaje

​Formato de respuesta de transmisión (SSE)

​5. Conversaciones

​Listar conversaciones

​Crear una conversación

​Recibir mensajes en una conversación

​Cancelar un mensaje en streaming

​Reintentar un mensaje fallido

​6. Rutinas

​Lista de rutinas

​Crear/actualizar una rutina

​Alternar una rutina

​Obtener historial de ejecución

​Ejecutar una rutina manualmente

​7. Aprobaciones

​Lista de aprobaciones pendientes

​Aprobar una acción

​Rechazar una acción

​8. Oportunidades

​Listar oportunidades

​Actualizar una oportunidad

​9. Estado y capacidades

​Obtener estado de asistente

​Obtener capacidades

​10. Privacidad y retención

​Obtener configuración de privacidad

​Eliminar todos los datos personales

​Obtener política de retención

​Actualizar política de retención

​11. Registro de auditoría

​Obtener registro de auditoría

​Exportar registro de auditoría

​12. Configuración y uso

​Actualizar configuración

​Obtener uso

​13. Diagnóstico de integración

​14. Manejo de errores

​Códigos de estado

​15. Mejores prácticas

​Chat en tiempo real

​Rutinas

​Aprobaciones

​Privacidad