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

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.

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:

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

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

{
  "message": "Resuma minhas 3 principais conversas abertas desta semana",
  "conversationId": "conv_abc123"
}

Exemplo (com streaming):

{
  "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):

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

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:

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

Retentar uma Mensagem com Falha

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

GET /api/personal-assistant/routines

Resposta:

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

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

Executar uma Rotina Manualmente

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

Corpo da Requisição:

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

GET /api/personal-assistant/approvals

Resposta:

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

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

Rejeitar uma Ação

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

GET /api/personal-assistant/opportunities

Atualizar uma Oportunidade

PATCH /api/personal-assistant/opportunities/{opportunityId}
Content-Type: application/json

Corpo da Requisição:

{
  "status": "actioned"
}

9. Estado e Capacidades

Obter Estado do Assistente

GET /api/personal-assistant/state

Obter Capacidades

GET /api/personal-assistant/capabilities

Resposta:

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

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

PATCH /api/personal-assistant/privacy/retention
Content-Type: application/json

Corpo da Requisição:

{
  "retentionDays": 30
}

11. Log de Auditoria

Cada ação realizada pela Livia é registrada para responsabilidade e revisão.

Obter Log de Auditoria

GET /api/personal-assistant/audit

Suporta paginação e filtragem por data via parâmetros de query.

Exportar Log de Auditoria

GET /api/personal-assistant/audit/export

12. Configurações e Uso

Obter Estatísticas de Uso

GET /api/personal-assistant/usage

Resposta:

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

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

​🔢 Sumário

​1. Visão Geral

​O que é a Livia - Assistente 360?

​Requisito de Plano

​2. Pré-requisitos

​3. Referência de Endpoints

​4. Chat

​Enviar uma Mensagem

​Formato de Resposta em Streaming (SSE)

​5. Conversas

​Listar Conversas

​Cancelar uma Mensagem em Streaming

​Retentar uma Mensagem com Falha

​6. Rotinas

​Listar Rotinas

​Ativar/Desativar uma Rotina

​Executar uma Rotina Manualmente

​7. Aprovações

​Listar Aprovações Pendentes

​Aprovar uma Ação

​Rejeitar uma Ação

​8. Oportunidades

​Listar Oportunidades

​Atualizar uma Oportunidade

​9. Estado e Capacidades

​Obter Estado do Assistente

​Obter Capacidades

​10. Privacidade e Retenção

​Excluir Todos os Dados Pessoais

​Atualizar Política de Retenção

​11. Log de Auditoria

​Obter Log de Auditoria

​Exportar Log de Auditoria

​12. Configurações e Uso

​Obter Estatísticas de Uso

​13. Diagnósticos de Integração

​14. Tratamento de Erros

​Status Codes

​15. Boas Práticas

​Chat em Streaming

​Rotinas

​Aprovações

​Privacidade

🔢 Sumário

1. Visão Geral

O que é a Livia - Assistente 360?

Requisito de Plano

2. Pré-requisitos

3. Referência de Endpoints

4. Chat

Enviar uma Mensagem

Formato de Resposta em Streaming (SSE)

5. Conversas

Listar Conversas

Cancelar uma Mensagem em Streaming

Retentar uma Mensagem com Falha

6. Rotinas

Listar Rotinas

Ativar/Desativar uma Rotina

Executar uma Rotina Manualmente

7. Aprovações

Listar Aprovações Pendentes

Aprovar uma Ação

Rejeitar uma Ação

8. Oportunidades

Listar Oportunidades

Atualizar uma Oportunidade

9. Estado e Capacidades

Obter Estado do Assistente

Obter Capacidades

10. Privacidade e Retenção

Excluir Todos os Dados Pessoais

Atualizar Política de Retenção

11. Log de Auditoria

Obter Log de Auditoria

Exportar Log de Auditoria

12. Configurações e Uso

Obter Estatísticas de Uso

13. Diagnósticos de Integração

14. Tratamento de Erros

Status Codes

15. Boas Práticas

Chat em Streaming

Rotinas

Aprovações

Privacidade