> ## 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 - Assistente 360 > Livia - Assistente 360 é sua assistente dentro do ZappWay — conversa, automatiza tarefas recorrentes por meio de rotinas, identifica oportunidades de negócio e mantém um histórico completo de auditoria de tudo que realiza. > **O que você vai aprender:** > Esta página cobre todos os recursos da Livia: conversas em chat, rotinas automatizadas, aprovações de ações, oportunidades de negócio, controles de privacidade, monitoramento de uso e diagnósticos de integração. *** ## 🔢 Sumário 1. [Visão Geral](#1-visao-geral) 2. [Pré-requisitos](#2-pre-requisitos) 3. [Referência de Endpoints](#3-referencia-de-endpoints) 4. [Chat](#4-chat) 5. [Conversas](#5-conversas) 6. [Rotinas](#6-rotinas) 7. [Aprovações](#7-aprovacoes) 8. [Oportunidades](#8-oportunidades) 9. [Estado e Capacidades](#9-estado-e-capacidades) 10. [Privacidade e Retenção](#10-privacidade-e-retencao) 11. [Log de Auditoria](#11-log-de-auditoria) 12. [Configurações e Uso](#12-configuracoes-e-uso) 13. [Diagnósticos de Integração](#13-diagnosticos-de-integracao) 14. [Tratamento de Erros](#14-tratamento-de-erros) 15. [Boas Práticas](#15-boas-praticas) *** ## 1. Visão Geral ### O que é a Livia - Assistente 360? A **Livia - Assistente 360** é um assistente de IA vinculado ao plano, construído diretamente no ZappWay. Ao contrário dos Funcionários IA (que lidam com conversas externas de clientes), a Livia trabalha **para você e sua equipe** internamente. **Capacidades Principais:** * 💬 **Chat em linguagem natural** com histórico completo de conversas * 🔄 **Rotinas automatizadas** — tarefas recorrentes executadas em cronograma * ✅ **Aprovações de ações** — revise ações propostas pela IA antes de executá-las * 📈 **Oportunidades de negócio** — insights identificados pela IA a partir dos seus dados * 🔒 **Controles de privacidade** — gestão completa de retenção de dados * 📋 **Log de auditoria** — histórico completo de cada ação realizada pelo assistente ### Requisito de Plano A Livia está disponível apenas em planos que incluem o recurso `personal_assistant`. Tentar acessar qualquer endpoint sem o plano necessário retorna: ```json theme={null} { "error": "Livia - 360 Assistant requires a PRO plan." } ``` *** ## 2. Pré-requisitos * Conta do ZappWay ativa com plano que inclui a Livia * Sessão autenticada (a Livia é sempre vinculada ao usuário) * Ao menos uma integração configurada para funcionalidade completa (opcional para chat básico) *** ## 3. Referência de Endpoints | Método | Endpoint | Descrição | Auth | | ----------------- | ------------------------------------------------------------------------ | --------------------------------------- | ---------------------------- | | `POST` | `/api/personal-assistant/chat` | Enviar mensagem (streaming SSE ou JSON) | `personal_assistant.execute` | | `GET` | `/api/personal-assistant/state` | Obter estado e contexto do assistente | `personal_assistant.read` | | `GET` | `/api/personal-assistant/capabilities` | Listar capacidades do assistente | `personal_assistant.read` | | `PATCH` | `/api/personal-assistant/settings` | Atualizar configurações | `personal_assistant.manage` | | `GET` | `/api/personal-assistant/usage` | Obter estatísticas de uso | `personal_assistant.read` | | `POST` | `/api/personal-assistant/feedback` | Enviar feedback sobre uma resposta | `personal_assistant.execute` | | `POST` | `/api/personal-assistant/context-help` | Obter ajuda contextual | `personal_assistant.read` | | **Conversas** | | | | | `GET` | `/api/personal-assistant/conversations` | Listar conversas | `personal_assistant.execute` | | `POST` | `/api/personal-assistant/conversations` | Criar uma conversa | `personal_assistant.execute` | | `PATCH` | `/api/personal-assistant/conversations/[id]` | Atualizar conversa | `personal_assistant.execute` | | `DELETE` | `/api/personal-assistant/conversations/[id]` | Excluir conversa | `personal_assistant.execute` | | `GET` | `/api/personal-assistant/conversations/[id]/messages` | Listar mensagens da conversa | `personal_assistant.read` | | `POST` | `/api/personal-assistant/conversations/[id]/messages/[messageId]/cancel` | Cancelar mensagem em streaming | `personal_assistant.execute` | | `POST` | `/api/personal-assistant/conversations/[id]/messages/[messageId]/retry` | Retentar mensagem com falha | `personal_assistant.execute` | | **Rotinas** | | | | | `GET` | `/api/personal-assistant/routines` | Listar rotinas | `personal_assistant.read` | | `POST` | `/api/personal-assistant/routines` | Criar/atualizar rotina | `personal_assistant.manage` | | `GET` | `/api/personal-assistant/routines/[id]` | Obter rotina específica | `personal_assistant.manage` | | `PATCH` | `/api/personal-assistant/routines/[id]` | Atualizar rotina | `personal_assistant.manage` | | `DELETE` | `/api/personal-assistant/routines/[id]` | Excluir rotina | `personal_assistant.manage` | | `POST` | `/api/personal-assistant/routines/[id]/toggle` | Ativar/desativar rotina | `personal_assistant.manage` | | `GET` | `/api/personal-assistant/routines/[id]/executions` | Histórico de execuções da rotina | `personal_assistant.read` | | `POST` | `/api/personal-assistant/routines/run` | Executar rotina manualmente | `personal_assistant.execute` | | **Aprovações** | | | | | `GET` | `/api/personal-assistant/approvals` | Listar aprovações pendentes | `personal_assistant.read` | | `POST` | `/api/personal-assistant/actions/[id]/approve` | Aprovar uma ação | `personal_assistant.execute` | | `POST` | `/api/personal-assistant/actions/[id]/reject` | Rejeitar uma ação | `personal_assistant.execute` | | **Oportunidades** | | | | | `GET` | `/api/personal-assistant/opportunities` | Listar oportunidades | `personal_assistant.read` | | `PATCH` | `/api/personal-assistant/opportunities/[id]` | Atualizar status da oportunidade | `personal_assistant.manage` | | **Privacidade** | | | | | `GET` | `/api/personal-assistant/privacy` | Obter configurações de privacidade | `personal_assistant.manage` | | `DELETE` | `/api/personal-assistant/privacy` | Excluir todos os dados pessoais | `personal_assistant.manage` | | `GET` | `/api/personal-assistant/privacy/retention` | Obter política de retenção | `personal_assistant.manage` | | `PATCH` | `/api/personal-assistant/privacy/retention` | Atualizar política de retenção | `personal_assistant.manage` | | **Auditoria** | | | | | `GET` | `/api/personal-assistant/audit` | Obter log de auditoria | `personal_assistant.audit` | | `GET` | `/api/personal-assistant/audit/export` | Exportar log de auditoria | `personal_assistant.audit` | | **Diagnósticos** | | | | | `GET` | `/api/personal-assistant/integrations/[integration]/diagnostics` | Diagnóstico de integração | `personal_assistant.manage` | *** ## 4. Chat ### Enviar uma Mensagem O endpoint de chat é o núcleo da Livia. Aceita uma mensagem e retorna uma resposta em **Server-Sent Events (SSE) em streaming** ou **JSON padrão**. ```bash theme={null} POST /api/personal-assistant/chat Content-Type: application/json ``` **Corpo da Requisição:** | Campo | Tipo | Obrigatório | Descrição | | ---------------- | --------- | ----------- | ------------------------------------------ | | `message` | `string` | ✅ | A mensagem do usuário | | `conversationId` | `string` | ❌ | Continuar uma conversa existente | | `stream` | `boolean` | ❌ | Retornar SSE em streaming. Padrão: `false` | **Exemplo (sem streaming):** ```json theme={null} { "message": "Resuma minhas 3 principais conversas abertas desta semana", "conversationId": "conv_abc123" } ``` **Exemplo (com streaming):** ```json theme={null} { "message": "Escreva uma resposta para a proposta enterprise da Acme Corp", "stream": true } ``` ### Formato de Resposta em Streaming (SSE) Quando `stream: true`, o endpoint retorna `Content-Type: text/event-stream`. **Eventos:** | Evento | Dados | Descrição | | ------- | ---------------------------------------------- | ------------------------------ | | `chunk` | `{ "delta": "texto parcial" }` | Fragmento de texto incremental | | `done` | Objeto resultado completo | Resposta final com metadados | | `error` | `{ "code": "CHAT_FAILED", "retryable": true }` | Ocorreu um erro | **Heartbeat:** Um comentário `: heartbeat` é enviado a cada 15 segundos para manter a conexão ativa. **Timeout:** Streams são fechados automaticamente após 90 segundos. **TypeScript (streaming):** ```ts theme={null} const response = await fetch('/api/personal-assistant/chat', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ message: 'Quais são minhas tarefas prioritárias para hoje?', stream: true, }), }); const reader = response.body!.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const text = decoder.decode(value); const lines = text.split('\n'); for (const line of lines) { if (line.startsWith('data: ')) { const data = JSON.parse(line.slice(6)); console.log(data); } } } ``` **Rate Limiting:** O endpoint de chat aplica limites de taxa baseados no plano. Headers de rate limit são incluídos em cada resposta. *** ## 5. Conversas A Livia mantém **histórico persistente de conversas**. Cada conversa é um thread de mensagens. ### Listar Conversas ```bash theme={null} GET /api/personal-assistant/conversations ``` Retorna todas as conversas do usuário autenticado, ordenadas por última atividade. ### Cancelar uma Mensagem em Streaming Se uma resposta em streaming estiver em andamento e você quiser interrompê-la: ```bash theme={null} POST /api/personal-assistant/conversations/{conversationId}/messages/{messageId}/cancel ``` ### Retentar uma Mensagem com Falha ```bash theme={null} POST /api/personal-assistant/conversations/{conversationId}/messages/{messageId}/retry ``` *** ## 6. Rotinas As **Rotinas** são tarefas automatizadas que executam em cronograma. A Livia pode executá-las automaticamente ou sob demanda. ### Listar Rotinas ```bash theme={null} GET /api/personal-assistant/routines ``` **Resposta:** ```json theme={null} { "items": [ { "id": "routine_abc123", "name": "Resumo Diário de Leads", "description": "Toda manhã, resumir novos leads das últimas 24 horas", "enabled": true, "schedule": "0 9 * * 1-5", "lastRunAt": "2025-01-15T09:00:00.000Z", "nextRunAt": "2025-01-16T09:00:00.000Z" } ] } ``` ### Ativar/Desativar uma Rotina Ative ou desative uma rotina sem excluí-la: ```bash theme={null} POST /api/personal-assistant/routines/{routineId}/toggle ``` ### Executar uma Rotina Manualmente ```bash theme={null} POST /api/personal-assistant/routines/run Content-Type: application/json ``` **Corpo da Requisição:** ```json theme={null} { "routineId": "routine_abc123" } ``` *** ## 7. Aprovações Algumas ações propostas pela Livia requerem sua **aprovação explícita** antes de serem executadas. ### Listar Aprovações Pendentes ```bash theme={null} GET /api/personal-assistant/approvals ``` **Resposta:** ```json theme={null} { "approvals": [ { "id": "approval_xyz", "actionType": "send_email", "description": "Enviar e-mail de acompanhamento para João Silva na Acme Corp", "payload": { "to": "joao@acme.com", "subject": "Acompanhamento da Proposta Enterprise", "body": "..." }, "createdAt": "2025-01-15T14:30:00.000Z" } ] } ``` ### Aprovar uma Ação ```bash theme={null} POST /api/personal-assistant/actions/{approvalId}/approve ``` ### Rejeitar uma Ação ```bash theme={null} POST /api/personal-assistant/actions/{approvalId}/reject ``` *** ## 8. Oportunidades A Livia identifica **oportunidades de negócio** — insights identificados pela IA a partir dos dados de conversas, contatos e integrações. ### Listar Oportunidades ```bash theme={null} GET /api/personal-assistant/opportunities ``` ### Atualizar uma Oportunidade ```bash theme={null} PATCH /api/personal-assistant/opportunities/{opportunityId} Content-Type: application/json ``` **Corpo da Requisição:** ```json theme={null} { "status": "actioned" } ``` *** ## 9. Estado e Capacidades ### Obter Estado do Assistente ```bash theme={null} GET /api/personal-assistant/state ``` ### Obter Capacidades ```bash theme={null} GET /api/personal-assistant/capabilities ``` **Resposta:** ```json theme={null} { "chat": true, "routines": true, "opportunities": true, "audit": true, "integrations": { "gmail": true, "calendar": false, "slack": true } } ``` *** ## 10. Privacidade e Retenção Você tem controle total sobre os dados que a Livia armazena. ### Excluir Todos os Dados Pessoais ```bash theme={null} DELETE /api/personal-assistant/privacy ``` > ⚠️ **Esta ação é irreversível.** Todo o histórico de conversas e dados pessoais serão excluídos permanentemente. ### Atualizar Política de Retenção ```bash theme={null} PATCH /api/personal-assistant/privacy/retention Content-Type: application/json ``` **Corpo da Requisição:** ```json theme={null} { "retentionDays": 30 } ``` *** ## 11. Log de Auditoria Cada ação realizada pela Livia é registrada para responsabilidade e revisão. ### Obter Log de Auditoria ```bash theme={null} GET /api/personal-assistant/audit ``` Suporta paginação e filtragem por data via parâmetros de query. ### Exportar Log de Auditoria ```bash theme={null} GET /api/personal-assistant/audit/export ``` *** ## 12. Configurações e Uso ### Obter Estatísticas de Uso ```bash theme={null} GET /api/personal-assistant/usage ``` **Resposta:** ```json theme={null} { "messagesThisMonth": 142, "routineExecutions": 38, "opportunitiesSurfaced": 12, "plan": { "messageLimit": 500, "routineLimit": 10 } } ``` *** ## 13. Diagnósticos de Integração Execute diagnósticos em uma integração específica para verificar conectividade e permissões: ```bash theme={null} GET /api/personal-assistant/integrations/{integration}/diagnostics ``` *** ## 14. Tratamento de Erros | Erro | Causa | Como Resolver | | ------------------------------------------- | ---------------------------------------- | --------------------------------------------- | | `Livia - 360 Assistant requires a PRO plan` | Plano não inclui a Livia | Faça upgrade do plano | | `Rate limit exceeded` | Muitas requisições de chat | Aguarde a janela de rate limit ser redefinida | | `REQUEST_CANCELED` | Cliente desconectado durante stream | O usuário cancelou — nenhuma ação necessária | | `CHAT_FAILED` | Erro interno durante o chat | Retentar a requisição | | `Routine not found` | ID de rotina inválido | Verifique se o ID da rotina existe | | `Approval not found` | ID de aprovação inválido ou já resolvido | Verifique se a aprovação já foi acionada | ### Status Codes | Status | Significado | | ------ | ---------------------------------------------- | | `200` | Requisição bem-sucedida | | `201` | Recurso criado | | `400` | Corpo inválido | | `401` | Não autenticado | | `403` | Permissões insuficientes ou restrição de plano | | `404` | Recurso não encontrado | | `429` | Rate limit excedido | | `500` | Erro interno do servidor | *** ## 15. Boas Práticas ### Chat em Streaming * Sempre implemente tratamento de desconexão no cliente para chamar o endpoint de **cancelamento** se o usuário navegar para outra página * Exiba um indicador de carregamento enquanto aguarda o primeiro evento `chunk` * Exiba texto progressivamente à medida que os eventos `chunk` chegam ### Rotinas * Comece com rotinas simples (ex: resumos diários) antes de automações complexas em múltiplas etapas * Use o **histórico de execuções** para verificar se as rotinas estão funcionando corretamente * Configure rotinas para rodar em horários de menor movimento (manhã cedo) ### Aprovações * Verifique aprovações pendentes regularmente — ações sensíveis ao tempo podem expirar * Revise o `payload` da ação cuidadosamente antes de aprovar, especialmente para ações que enviam comunicações externas * Use o endpoint `reject` para fornecer feedback que ajuda o assistente a aprender suas preferências ### Privacidade * Defina uma política de retenção que atenda aos requisitos de governança de dados da sua organização * Exporte o log de auditoria periodicamente para registros de conformidade * Use `DELETE /privacy` como parte dos fluxos de offboarding para membros que saem da equipe