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

What you will learn: This page covers every feature of Livia: chat conversations, automated routines, action approvals, business opportunities, privacy controls, usage tracking, and integration diagnostics.

🔢 Table of Contents

Overview
Prerequisites
Endpoint Reference
Chat
Conversations
Routines
Approvals
Opportunities
State & Capabilities
Privacy & Retention
Audit Log
Settings & Usage
Integration Diagnostics
Error Handling
Best Practices

1. Overview

What is Livia - 360 Assistant?

Livia - 360 Assistant is a plan-gated AI assistant built directly into ZappWay. Unlike the AI Employees (which handle external customer conversations), Livia works for you and your team internally. Key Capabilities:

💬 Natural language chat with full conversation history
🔄 Automated routines — recurring tasks that run on schedule
✅ Action approvals — review AI-proposed actions before they execute
📈 Business opportunities — AI-surfaced insights from your data
🔒 Privacy controls — full data retention management
📋 Audit log — complete history of every action the assistant took

Plan Requirement

Livia is available only on plans that include the personal_assistant feature flag. Attempting to access any endpoint without the required plan returns:

{ "error": "Livia - 360 Assistant requires a PRO plan." }

2. Prerequisites

Active ZappWay account with a plan that includes Livia
Authenticated session (Livia is always user-bound, not organization-bound at the chat level)
At least one integration configured for full functionality (optional for basic chat)

3. Endpoint Reference

Method	Endpoint	Description	Auth
`POST`	`/api/personal-assistant/chat`	Send a message (streaming SSE or JSON)	`personal_assistant.execute`
`GET`	`/api/personal-assistant/state`	Get assistant state and context	`personal_assistant.read`
`GET`	`/api/personal-assistant/capabilities`	List assistant capabilities	`personal_assistant.read`
`PATCH`	`/api/personal-assistant/settings`	Update assistant settings	`personal_assistant.manage`
`GET`	`/api/personal-assistant/usage`	Get usage statistics	`personal_assistant.read`
`POST`	`/api/personal-assistant/feedback`	Submit feedback on a response	`personal_assistant.execute`
`POST`	`/api/personal-assistant/context-help`	Get contextual help	`personal_assistant.read`
Conversations
`GET`	`/api/personal-assistant/conversations`	List conversations	`personal_assistant.execute`
`POST`	`/api/personal-assistant/conversations`	Create a conversation	`personal_assistant.execute`
`PATCH`	`/api/personal-assistant/conversations/[id]`	Update conversation	`personal_assistant.execute`
`DELETE`	`/api/personal-assistant/conversations/[id]`	Delete conversation	`personal_assistant.execute`
`GET`	`/api/personal-assistant/conversations/[id]/messages`	List messages in conversation	`personal_assistant.read`
`POST`	`/api/personal-assistant/conversations/[id]/messages/[messageId]/cancel`	Cancel a streaming message	`personal_assistant.execute`
`POST`	`/api/personal-assistant/conversations/[id]/messages/[messageId]/retry`	Retry a failed message	`personal_assistant.execute`
Routines
`GET`	`/api/personal-assistant/routines`	List routines	`personal_assistant.read`
`POST`	`/api/personal-assistant/routines`	Create/update a routine	`personal_assistant.manage`
`GET`	`/api/personal-assistant/routines/[id]`	Get a specific routine	`personal_assistant.manage`
`PATCH`	`/api/personal-assistant/routines/[id]`	Update a routine	`personal_assistant.manage`
`DELETE`	`/api/personal-assistant/routines/[id]`	Delete a routine	`personal_assistant.manage`
`POST`	`/api/personal-assistant/routines/[id]/toggle`	Enable/disable a routine	`personal_assistant.manage`
`GET`	`/api/personal-assistant/routines/[id]/executions`	Get routine execution history	`personal_assistant.read`
`POST`	`/api/personal-assistant/routines/run`	Manually trigger a routine	`personal_assistant.execute`
Approvals
`GET`	`/api/personal-assistant/approvals`	List pending approvals	`personal_assistant.read`
`POST`	`/api/personal-assistant/actions/[id]/approve`	Approve an action	`personal_assistant.execute`
`POST`	`/api/personal-assistant/actions/[id]/reject`	Reject an action	`personal_assistant.execute`
Opportunities
`GET`	`/api/personal-assistant/opportunities`	List opportunities	`personal_assistant.read`
`PATCH`	`/api/personal-assistant/opportunities/[id]`	Update opportunity status	`personal_assistant.manage`
Privacy
`GET`	`/api/personal-assistant/privacy`	Get privacy settings	`personal_assistant.manage`
`DELETE`	`/api/personal-assistant/privacy`	Delete all personal data	`personal_assistant.manage`
`GET`	`/api/personal-assistant/privacy/retention`	Get retention policy	`personal_assistant.manage`
`PATCH`	`/api/personal-assistant/privacy/retention`	Update retention policy	`personal_assistant.manage`
Audit
`GET`	`/api/personal-assistant/audit`	Get audit log	`personal_assistant.audit`
`GET`	`/api/personal-assistant/audit/export`	Export audit log	`personal_assistant.audit`
Diagnostics
`GET`	`/api/personal-assistant/integrations/[integration]/diagnostics`	Run integration diagnostics	`personal_assistant.manage`

4. Chat

Send a Message

The chat endpoint is the core of Livia. It accepts a message and returns either a streaming Server-Sent Events (SSE) response or a standard JSON response.

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

Request Body:

Field	Type	Required	Description
`message`	`string`	✅	The user’s message
`requestedInteractionLanguage`	locale code	❌	Explicitly choose Livia’s response language for this conversation; independent from the interface locale
`conversationId`	`string`	❌	Continue an existing conversation
`stream`	`boolean`	❌	Return SSE stream. Default: `false`
`context`	`object`	❌	Current route, query/hash, active tabs, transient UI states, safe actions, and optional explicitly consented screenshot

Example (non-streaming):

{
  "message": "Summarize my top 3 open conversations from this week",
  "requestedInteractionLanguage": "en",
  "conversationId": "conv_abc123",
  "context": {
    "contextRoute": "/analytics?period=7d#response-performance",
    "metadata": {
      "activeTab": "overview"
    }
  }
}

Livia keeps the interaction language stable across the conversation. Short ambiguous replies such as “ok” do not replace that choice. Interface labels continue to use the account’s interface locale. Route and integration guidance is generated from verified product teachings. If a route, action, or integration capability cannot be verified, Livia reports that limitation rather than inventing a label, link, or executable action. Example (streaming):

{
  "message": "Write a draft response to the enterprise proposal from Acme Corp",
  "stream": true
}

Streaming Response Format (SSE)

When stream: true, the endpoint returns Content-Type: text/event-stream. Events:

Event	Data	Description
`chunk`	`{ "delta": "partial text" }`	Incremental text chunk
`done`	Full result object	Final response with metadata
`error`	`{ "code": "CHAT_FAILED", "retryable": true }`	Error occurred

Heartbeat: A : heartbeat comment is sent every 15 seconds to keep the connection alive. Timeout: Streams are automatically closed after 90 seconds. TypeScript (streaming):

const response = await fetch('/api/personal-assistant/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: 'What are my priority tasks for today?',
    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: The chat endpoint enforces plan-based rate limits. Rate limit headers are included in every response:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

5. Conversations

Livia maintains persistent conversation history. Each conversation is a thread of messages.

List Conversations

GET /api/personal-assistant/conversations

Returns all conversations for the authenticated user, ordered by last activity.

Create a Conversation

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

Get Messages in a Conversation

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

Cancel a Streaming Message

If a streaming response is in progress and you want to stop it:

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

Retry a Failed Message

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

6. Routines

Routines are automated tasks that run on a schedule. Livia can execute routines automatically or on demand.

List Routines

GET /api/personal-assistant/routines

Response:

{
  "items": [
    {
      "id": "routine_abc123",
      "name": "Daily Leads Summary",
      "description": "Every morning, summarize new leads from the last 24 hours",
      "enabled": true,
      "schedule": "0 9 * * 1-5",
      "lastRunAt": "2025-01-15T09:00:00.000Z",
      "nextRunAt": "2025-01-16T09:00:00.000Z"
    }
  ]
}

Create/Update a Routine

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

Toggle a Routine

Enable or disable a routine without deleting it:

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

Get Execution History

GET /api/personal-assistant/routines/{routineId}/executions

Returns the last N executions of a routine, including status (success/failed) and output.

Run a Routine Manually

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

Request Body:

{
  "routineId": "routine_abc123"
}

7. Approvals

Some actions proposed by Livia require your explicit approval before execution. The approvals system gives you full control over automated actions.

List Pending Approvals

GET /api/personal-assistant/approvals

Response:

{
  "approvals": [
    {
      "id": "approval_xyz",
      "actionType": "send_email",
      "description": "Send follow-up email to John Smith at Acme Corp",
      "payload": {
        "to": "john@acme.com",
        "subject": "Follow-up on Enterprise Proposal",
        "body": "..."
      },
      "createdAt": "2025-01-15T14:30:00.000Z"
    }
  ]
}

Approve an Action

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

The action executes immediately upon approval.

Reject an Action

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

The action is discarded. You can optionally provide a reason.

8. Opportunities

Livia surfaces business opportunities — AI-identified insights from your conversation data, contacts, and integrations.

List Opportunities

GET /api/personal-assistant/opportunities

Update an Opportunity

Mark an opportunity as actioned, dismissed, or in-progress:

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

Request Body:

{
  "status": "actioned"
}

9. State & Capabilities

Get Assistant State

Returns the current state of Livia, including context, integrations status, and active features.

GET /api/personal-assistant/state

Get Capabilities

Returns the list of actions and features available to the assistant based on your plan and configured integrations.

GET /api/personal-assistant/capabilities

Response:

{
  "chat": true,
  "routines": true,
  "opportunities": true,
  "audit": true,
  "integrations": {
    "gmail": true,
    "calendar": false,
    "slack": true
  }
}

10. Privacy & Retention

You have full control over the data Livia stores.

Get Privacy Settings

GET /api/personal-assistant/privacy

Delete All Personal Data

Permanently deletes all conversation history, routine data, and personal context stored by the assistant.

DELETE /api/personal-assistant/privacy

⚠️ This action is irreversible. All conversation history and personal data will be permanently deleted.

Get Retention Policy

GET /api/personal-assistant/privacy/retention

Update Retention Policy

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

Request Body:

{
  "retentionDays": 30
}

11. Audit Log

Every action Livia takes is logged for accountability and review.

Get Audit Log

GET /api/personal-assistant/audit

Supports pagination and date filtering via query parameters.

Export Audit Log

Download the full audit log as a file:

GET /api/personal-assistant/audit/export

The response is a downloadable file (CSV or JSON format, based on implementation).

12. Settings & Usage

Update Settings

Configure Livia behavior:

PATCH /api/personal-assistant/settings
Content-Type: application/json

Get Usage

View your Livia usage statistics (message count, routine executions, etc.):

GET /api/personal-assistant/usage

Response:

{
  "messagesThisMonth": 142,
  "routineExecutions": 38,
  "opportunitiesSurfaced": 12,
  "plan": {
    "messageLimit": 500,
    "routineLimit": 10
  }
}

13. Integration Diagnostics

Run diagnostics on a specific integration to verify connectivity and permissions:

GET /api/personal-assistant/integrations/{integration}/diagnostics

Path Parameters:

Parameter	Type	Description
`integration`	`string`	Integration identifier (e.g., `gmail`, `slack`, `calendar`)

14. Error Handling

Error	Cause	How to Fix
`Livia - 360 Assistant requires a PRO plan`	Plan does not include Livia	Upgrade your plan
`Rate limit exceeded`	Too many chat requests	Wait for the rate limit window to reset
`REQUEST_CANCELED`	Client disconnected during stream	The user canceled — no action needed
`CHAT_FAILED`	Internal error during chat	Retry the request
`Routine not found`	Invalid routine ID	Verify the routine ID exists
`Approval not found`	Invalid approval ID or already resolved	Check if the approval was already actioned

Status Codes

Status	Meaning
`200`	Request successful
`201`	Resource created
`400`	Invalid request body
`401`	Not authenticated
`403`	Insufficient permissions or plan restriction
`404`	Resource not found
`429`	Rate limit exceeded
`500`	Internal server error

15. Best Practices

Streaming Chat

Always implement client-side disconnect handling to call the cancel endpoint if the user navigates away
Show a loading indicator while waiting for the first chunk event
Display text progressively as chunk events arrive for a better UX

Routines

Start with simple routines (e.g., daily summaries) before complex multi-step automations
Use the execution history to verify routines are running correctly before enabling new ones
Set up routines to run during off-peak hours (early morning) to avoid competing with interactive usage

Approvals

Check pending approvals regularly — time-sensitive actions may expire
Review the action payload carefully before approving, especially for actions that send external communications
Use the reject endpoint to provide feedback that helps the assistant learn your preferences

Privacy

Set a retention policy that matches your organization’s data governance requirements
Export the audit log periodically for compliance records
Use DELETE /privacy as part of offboarding workflows for departing team members

​🔢 Table of Contents

​1. Overview

​What is Livia - 360 Assistant?

​Plan Requirement

​2. Prerequisites

​3. Endpoint Reference

​4. Chat

​Send a Message

​Streaming Response Format (SSE)

​5. Conversations

​List Conversations

​Create a Conversation

​Get Messages in a Conversation

​Cancel a Streaming Message

​Retry a Failed Message

​6. Routines

​List Routines

​Create/Update a Routine

​Toggle a Routine

​Get Execution History

​Run a Routine Manually

​7. Approvals

​List Pending Approvals

​Approve an Action

​Reject an Action

​8. Opportunities

​List Opportunities

​Update an Opportunity

​9. State & Capabilities

​Get Assistant State

​Get Capabilities

​10. Privacy & Retention

​Get Privacy Settings

​Delete All Personal Data

​Get Retention Policy

​Update Retention Policy

​11. Audit Log

​Get Audit Log

​Export Audit Log

​12. Settings & Usage

​Update Settings

​Get Usage

​13. Integration Diagnostics

​14. Error Handling

​Status Codes

​15. Best Practices

​Streaming Chat

​Routines

​Approvals

​Privacy

🔢 Table of Contents

1. Overview

What is Livia - 360 Assistant?

Plan Requirement

2. Prerequisites

3. Endpoint Reference

4. Chat

Send a Message

Streaming Response Format (SSE)

5. Conversations

List Conversations

Create a Conversation

Get Messages in a Conversation

Cancel a Streaming Message

Retry a Failed Message

6. Routines

List Routines

Create/Update a Routine

Toggle a Routine

Get Execution History

Run a Routine Manually

7. Approvals

List Pending Approvals

Approve an Action

Reject an Action

8. Opportunities

List Opportunities

Update an Opportunity

9. State & Capabilities

Get Assistant State

Get Capabilities

10. Privacy & Retention

Get Privacy Settings

Delete All Personal Data

Get Retention Policy

Update Retention Policy

11. Audit Log

Get Audit Log

Export Audit Log

12. Settings & Usage

Update Settings

Get Usage

13. Integration Diagnostics

14. Error Handling

Status Codes

15. Best Practices

Streaming Chat

Routines

Approvals

Privacy