# Trillet AI - Complete Documentation

> This file contains the complete documentation for Trillet AI.
> Total pages: 150

---

## Introduction

*Starter project with example pages, components, and auto-deploy from GitHub. Edit MDX files, customize your theme, and go live in minutes.*

Welcome to your documentation site. This starter project has everything you need to get up and running.

## What's included

<Columns cols={2}>
  <Card title="Ready-made pages" icon="file-lines">
    Example pages showing how to structure your docs with headings, lists, and components.
  </Card>
  <Card title="Component examples" icon="puzzle-piece">
    Cards, callouts, tabs, steps, and more — all ready to use.
  </Card>
  <Card title="Auto-deploy" icon="rocket">
    Push to GitHub and your docs build and deploy automatically.
  </Card>
  <Card title="Customizable" icon="palette">
    Change colors, logo, navigation, and theme in `docs.json`.
  </Card>
</Columns>

## Next steps

<Card title="Quickstart" icon="play" href="/quickstart">
  Learn how to edit pages, customize your site, and deploy changes.
</Card>

---

## Quickstart

*Edit MDX files, add new pages to your navigation, customize colors and branding in docs.json, and preview locally with the Jamdesk CLI.*

Your docs are built from MDX files in this repository. Every push to GitHub triggers an automatic build and deploy.

## Edit a page

Open any `.mdx` file and start writing. MDX supports standard Markdown plus Jamdesk components.

```mdx
---
title: My Page
description: A brief description for SEO
---

# Heading

Regular markdown works — **bold**, *italic*, `code`, [links](https://example.com).
```

## Add a new page

<Steps>
  <Step title="Create an MDX file">
    Add a new `.mdx` file anywhere in your project, for example `guides/deployment.mdx`.
  </Step>
  <Step title="Add it to navigation">
    Open `docs.json` and add the page path to the `navigation` section:

    ```json
    {
      "group": "Guides",
      "pages": ["guides/deployment"]
    }
    ```
  </Step>
  <Step title="Push to GitHub">
    Commit and push. Your site will rebuild automatically.
  </Step>
</Steps>

## Customize your site

Everything is configured in `docs.json`:

| Setting | What it does |
|---------|-------------|
| `name` | Site name shown in the header |
| `colors` | Primary, light, and dark accent colors |
| `logo` | Light and dark mode logo images |
| `theme` | Visual theme (`jam`, `nebula`, or `pulsar`) |
| `navigation` | Sidebar tabs, groups, and page order |
| `navbar` | Top navigation links and buttons |

<Tip>
See the full configuration reference at [jamdesk.com/docs](https://jamdesk.com/docs).
</Tip>

## Use the CLI

Install the Jamdesk CLI for local development:

```bash
npm install -g jamdesk
```

Preview your docs locally:

```bash
jamdesk dev
```

This starts a local server with hot reload so you can see changes instantly.

---

## Callouts

*Draw attention to important information with Note, Tip, Warning, Danger, and Check callouts. Supports custom titles and rich Markdown content.*

Callouts draw attention to key information.

## Types

<Note>
Helpful context or additional information.
</Note>

<Tip>
Best practices or optimization suggestions.
</Tip>

<Warning>
Important caveats or requirements.
</Warning>

<Danger>
Critical warnings — actions that could cause data loss.
</Danger>

<Check>
Success confirmations or completed steps.
</Check>

## Usage

```mdx
<Note>
Helpful context or additional information.
</Note>

<Warning>
Important caveats or requirements.
</Warning>
```

## With custom title

<Note title="Did you know?">
You can use **Markdown** inside callouts, including `code` and [links](/introduction).
</Note>

```mdx
<Note title="Did you know?">
You can use **Markdown** inside callouts.
</Note>
```

---

## Cards

*Create linked feature grids and navigation panels with Card and Columns components. Supports icons, descriptions, and click-through links.*

## Basic card

<Card title="Getting Started">
  A simple card with a title and content.
</Card>

```mdx
<Card title="Getting Started">
  A simple card with a title and content.
</Card>
```

## Card with icon

<Card title="Documentation" icon="book">
  Add an icon for visual emphasis.
</Card>

```mdx
<Card title="Documentation" icon="book">
  Add an icon for visual emphasis.
</Card>
```

## Card with link

<Card title="Quickstart Guide" icon="play" href="/quickstart">
  Cards can link to other pages.
</Card>

```mdx
<Card title="Quickstart Guide" icon="play" href="/quickstart">
  Cards can link to other pages.
</Card>
```

## Card group

Use `Columns` to arrange cards in a grid:

<Columns cols={2}>
  <Card title="Docs" icon="book">
    Documentation
  </Card>
  <Card title="API" icon="code">
    API Reference
  </Card>
  <Card title="Guides" icon="graduation-cap">
    Tutorials
  </Card>
  <Card title="Support" icon="life-ring">
    Get help
  </Card>
</Columns>

```mdx
<Columns cols={2}>
  <Card title="Docs" icon="book">Documentation</Card>
  <Card title="API" icon="code">API Reference</Card>
</Columns>
```

## Properties

<ParamField name="title" type="string" required>
  The title displayed at the top of the card.
</ParamField>

<ParamField name="icon" type="string">
  Font Awesome icon name (e.g., "book", "code", "rocket").
</ParamField>

<ParamField name="href" type="string">
  URL the card links to.
</ParamField>

---

## Steps

*Break multi-step processes into numbered instructions with Steps and Step components. Each step gets a title and supports rich content.*

Use Steps for ordered instructions:

<Steps>
  <Step title="Install the CLI">
    ```bash
    npm install -g jamdesk
    ```
  </Step>
  <Step title="Initialize your project">
    ```bash
    jamdesk init
    ```
  </Step>
  <Step title="Start writing">
    Open your project and create `.mdx` files. Each file becomes a page in your docs.
  </Step>
</Steps>

## Usage

```mdx
<Steps>
  <Step title="First step">
    Description of what to do.
  </Step>
  <Step title="Second step">
    Next instruction.
  </Step>
</Steps>
```

<Tip>
Steps work well for setup guides, tutorials, and getting-started flows.
</Tip>

---

## Tabs & Accordions

*Organize content with Tabs for language or platform variants and AccordionGroup for collapsible FAQ-style sections that save vertical space.*

## Tabs

Show content in switchable panels:

<Tabs>
  <Tab title="React">
    ```jsx
    function App() {
      return <h1>Hello React</h1>;
    }
    ```
  </Tab>
  <Tab title="Vue">
    ```html
    <template>
      <h1>Hello Vue</h1>
    </template>
    ```
  </Tab>
  <Tab title="Svelte">
    ```html
    <h1>Hello Svelte</h1>
    ```
  </Tab>
</Tabs>

```mdx
<Tabs>
  <Tab title="React">
    Content for the React tab.
  </Tab>
  <Tab title="Vue">
    Content for the Vue tab.
  </Tab>
</Tabs>
```

## Accordions

Collapsible sections for optional details:

<AccordionGroup>
  <Accordion title="What is Jamdesk?">
    Jamdesk is a documentation platform that builds and hosts your docs from MDX files in a GitHub repository.
  </Accordion>
  <Accordion title="How do I deploy?">
    Push to GitHub. Jamdesk builds and deploys automatically on every push.
  </Accordion>
  <Accordion title="Can I use a custom domain?">
    Yes. Configure your custom domain in the Jamdesk dashboard under project settings.
  </Accordion>
</AccordionGroup>

```mdx
<AccordionGroup>
  <Accordion title="Question here">
    Answer here.
  </Accordion>
</AccordionGroup>
```

---

## Introduction

*Example section for showcasing API endpoints*

<Note>
  If you're not looking to build API reference documentation, you can delete
  this section by removing the api-reference folder.
</Note>

## Welcome

There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification.

<Card
  title="Plant Store Endpoints"
  icon="leaf"
  href="https://github.com/mintlify/starter/blob/main/api-reference/openapi.json"
>
  View the OpenAPI specification file
</Card>

## Authentication

All API endpoints are authenticated using Bearer tokens and picked up from the specification file.

```json
"security": [
  {
    "bearerAuth": []
  }
]
```

---

## Trillet Change Log

*View the latest changes to Trillet*

---

## API Best Practices

*Guidelines for integrating with Trillet AI API*

## Authentication

### API Keys

- Keep your API keys secure and never expose them in client-side code
- Use different API keys for development and production
- Rotate your API keys periodically
- Monitor your API key usage for suspicious activity

```bash
# API Key format
xxxxxxxxxxxxxxxxxxx
```

## Error Handling

Implement proper error handling for API responses:

```bash
curl -X POST https://api.trillet.ai/api/v1/calls/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_123",
    "toNumber": "+1234567890"
  }'
```

Common error responses:
```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has insufficient credits"
  }
}
```

```json
{
  "error": {
    "code": "invalid_number",
    "message": "The provided phone number is invalid"
  }
}
```

## Rate Limits

- Production API keys are limited to 60 requests per minute
- Implement backoff when you hit rate limits
- Monitor your API usage in the dashboard

Rate limit response:
```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again in 60 seconds.",
    "reset_at": "2024-01-22T15:30:00Z"
  }
}
```

## Webhooks [Coming Soon!]


### Configuring Webhooks

1. Add your webhook URL in the dashboard
2. Configure the events you want to receive
3. Store your webhook secret securely

### Verifying Webhooks

Always verify webhook signatures using the `X-Trillet-Signature` header:

```bash
# Your webhook secret from the dashboard
WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx

# Verify the signature before processing webhooks
echo -n "$PAYLOAD" | openssl sha256 -hmac "$WEBHOOK_SECRET"
```

### Webhook Events

- `call.started` - When a call begins
- `call.completed` - When a call ends
- `call.failed` - When a call fails
- `sms.sent` - When an SMS is sent
- `sms.delivered` - When an SMS is delivered

Example webhook payload:
```json
{
  "event": "call.completed",
  "data": {
    "callId": "call_xyz789",
    "agentId": "agent_123abc",
    "duration": 125,
    "status": "completed"
  }
}
```

## Production Checklist

1. **Authentication**
   - Use production API keys
   - Implement key rotation
   - Secure key storage

2. **Error Handling**
   - Handle all error codes
   - Implement retry logic
   - Log errors appropriately

3. **Monitoring**
   - Track API response times
   - Monitor error rates
   - Set up alerts

4. **Webhooks**
   - Use HTTPS endpoints
   - Verify signatures
   - Implement retry logic
   - Handle duplicate events

## Need Help?

<Columns cols={2}>
  <Card
    title="API Status [Coming Soon!]"
    icon="signal"
  >
    Check our API status and uptime
  </Card>
  <Card
    title="Support"
    icon="headset"
    href="mailto:support@trillet.ai"
  >
    Get technical support
  </Card>
</Columns>

---

## Webhook Integration Guide [Coming Soon]

## Introduction
This guide will help you integrate and set up webhooks for inbound AI-powered calls. It explains how to configure webhook settings, set up an API receiver, and dynamically replace variables in AI-generated prompts.

## Prerequisites
Before you begin, make sure you have:
- An account for your application.
- A valid URL to handle webhook calls.


## Configure Webhook Settings
To get started, set up your webhook URL, headers, and query parameters.
- Enter your webhook URL
- Add your API authentication details, such as bearer tokens or API keys.
- Include any dynamic parameters you wish to pass, such as customer_name and order_status.
![title](/images/Inboundwebhook.png)

## Create an API Receiver
- Create an API endpoint to process incoming webhook requests.

```bash
app.get('/get-webhook', (req, res) => {
    console.log("Request Headers: ", req.headers);
    console.log("Request Query: ", req.query);

    // Respond with variables for AI prompt
    res.status(200).json({
        variables: {
            customer_name: "John Doe",
            order_status: "shipped"
        }
    });
});
```

Note: The API response should always include the variables object in the following format:
```bash
{
    "variables": {
        "customer_name": "John Doe",
        "order_status": "shipped"
    }
}
```

## Replace Variable in AI Prompts
Use the returned variables from your webhook to dynamically update AI prompts.

Example Prompt in Call Flow Designer:
```bash
Hello, {{customer_name}}, your order status is {{order_status}}.
```

When the webhook processes the request, variables are replaced dynamically:

```bash
Hello, John Doe, your order status is shipped.
```

---

## documentation/introduction

![Trillet Logo](/logo/Trillet-logo-light.png =200x)


<video
  autoPlay
  controls
  muted
  loop
  playsInline
  className="w-full aspect-video rounded-xl"
  poster="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAU8AAAFrCAYAAABR8AvSAAAAAXNSR0IArs4c6QAACzhJREFUeF7t1LEJACAQBEHtv17BTMEO3HiM/WQ4dq59zvAIECBA4EtgiueXl88ECBB4AuJpCAQIEAgC4hnQnBAgQEA8bYAAAQJBQDwDmhMCBAiIpw0QIEAgCIhnQHNCgAAB8bQBAgQIBAHxDGhOCBAgIJ42QIAAgSAgngHNCQECBMTTBggQIBAExDOgOSFAgIB42gABAgSCgHgGNCcECBAQTxsgQIBAEBDPgOaEAAEC4mkDBAgQCALiGdCcECBAQDxtgAABAkFAPAOaEwIECIinDRAgQCAIiGdAc0KAAAHxtAECBAgEAfEMaE4IECAgnjZAgACBICCeAc0JAQIExNMGCBAgEATEM6A5IUCAgHjaAAECBIKAeAY0JwQIEBBPGyBAgEAQEM+A5oQAAQLiaQMECBAIAuIZ0JwQIEBAPG2AAAECQUA8A5oTAgQIiKcNECBAIAiIZ0BzQoAAAfG0AQIECAQB8QxoTggQICCeNkCAAIEgIJ4BzQkBAgTE0wYIECAQBMQzoDkhQICAeNoAAQIEgoB4BjQnBAgQEE8bIECAQBAQz4DmhAABAuJpAwQIEAgC4hnQnBAgQEA8bYAAAQJBQDwDmhMCBAiIpw0QIEAgCIhnQHNCgAAB8bQBAgQIBAHxDGhOCBAgIJ42QIAAgSAgngHNCQECBMTTBggQIBAExDOgOSFAgIB42gABAgSCgHgGNCcECBAQTxsgQIBAEBDPgOaEAAEC4mkDBAgQCALiGdCcECBAQDxtgAABAkFAPAOaEwIECIinDRAgQCAIiGdAc0KAAAHxtAECBAgEAfEMaE4IECAgnjZAgACBICCeAc0JAQIExNMGCBAgEATEM6A5IUCAgHjaAAECBIKAeAY0JwQIEBBPGyBAgEAQEM+A5oQAAQLiaQMECBAIAuIZ0JwQIEBAPG2AAAECQUA8A5oTAgQIiKcNECBAIAiIZ0BzQoAAAfG0AQIECAQB8QxoTggQICCeNkCAAIEgIJ4BzQkBAgTE0wYIECAQBMQzoDkhQICAeNoAAQIEgoB4BjQnBAgQEE8bIECAQBAQz4DmhAABAuJpAwQIEAgC4hnQnBAgQEA8bYAAAQJBQDwDmhMCBAiIpw0QIEAgCIhnQHNCgAAB8bQBAgQIBAHxDGhOCBAgIJ42QIAAgSAgngHNCQECBMTTBggQIBAExDOgOSFAgIB42gABAgSCgHgGNCcECBAQTxsgQIBAEBDPgOaEAAEC4mkDBAgQCALiGdCcECBAQDxtgAABAkFAPAOaEwIECIinDRAgQCAIiGdAc0KAAAHxtAECBAgEAfEMaE4IECAgnjZAgACBICCeAc0JAQIExNMGCBAgEATEM6A5IUCAgHjaAAECBIKAeAY0JwQIEBBPGyBAgEAQEM+A5oQAAQLiaQMECBAIAuIZ0JwQIEBAPG2AAAECQUA8A5oTAgQIiKcNECBAIAiIZ0BzQoAAAfG0AQIECAQB8QxoTggQICCeNkCAAIEgIJ4BzQkBAgTE0wYIECAQBMQzoDkhQICAeNoAAQIEgoB4BjQnBAgQEE8bIECAQBAQz4DmhAABAuJpAwQIEAgC4hnQnBAgQEA8bYAAAQJBQDwDmhMCBAiIpw0QIEAgCIhnQHNCgAAB8bQBAgQIBAHxDGhOCBAgIJ42QIAAgSAgngHNCQECBMTTBggQIBAExDOgOSFAgIB42gABAgSCgHgGNCcECBAQTxsgQIBAEBDPgOaEAAEC4mkDBAgQCALiGdCcECBAQDxtgAABAkFAPAOaEwIECIinDRAgQCAIiGdAc0KAAAHxtAECBAgEAfEMaE4IECAgnjZAgACBICCeAc0JAQIExNMGCBAgEATEM6A5IUCAgHjaAAECBIKAeAY0JwQIEBBPGyBAgEAQEM+A5oQAAQLiaQMECBAIAuIZ0JwQIEBAPG2AAAECQUA8A5oTAgQIiKcNECBAIAiIZ0BzQoAAAfG0AQIECAQB8QxoTggQICCeNkCAAIEgIJ4BzQkBAgTE0wYIECAQBMQzoDkhQICAeNoAAQIEgoB4BjQnBAgQEE8bIECAQBAQz4DmhAABAuJpAwQIEAgC4hnQnBAgQEA8bYAAAQJBQDwDmhMCBAiIpw0QIEAgCIhnQHNCgAAB8bQBAgQIBAHxDGhOCBAgIJ42QIAAgSAgngHNCQECBMTTBggQIBAExDOgOSFAgIB42gABAgSCgHgGNCcECBAQTxsgQIBAEBDPgOaEAAEC4mkDBAgQCALiGdCcECBAQDxtgAABAkFAPAOaEwIECIinDRAgQCAIiGdAc0KAAAHxtAECBAgEAfEMaE4IECAgnjZAgACBICCeAc0JAQIExNMGCBAgEATEM6A5IUCAgHjaAAECBIKAeAY0JwQIEBBPGyBAgEAQEM+A5oQAAQLiaQMECBAIAuIZ0JwQIEBAPG2AAAECQUA8A5oTAgQIiKcNECBAIAiIZ0BzQoAAAfG0AQIECAQB8QxoTggQICCeNkCAAIEgIJ4BzQkBAgTE0wYIECAQBMQzoDkhQICAeNoAAQIEgoB4BjQnBAgQEE8bIECAQBAQz4DmhAABAuJpAwQIEAgC4hnQnBAgQEA8bYAAAQJBQDwDmhMCBAiIpw0QIEAgCIhnQHNCgAAB8bQBAgQIBAHxDGhOCBAgIJ42QIAAgSAgngHNCQECBMTTBggQIBAExDOgOSFAgIB42gABAgSCgHgGNCcECBAQTxsgQIBAEBDPgOaEAAEC4mkDBAgQCALiGdCcECBAQDxtgAABAkFAPAOaEwIECIinDRAgQCAIiGdAc0KAAAHxtAECBAgEAfEMaE4IECAgnjZAgACBICCeAc0JAQIExNMGCBAgEATEM6A5IUCAgHjaAAECBIKAeAY0JwQIEBBPGyBAgEAQEM+A5oQAAQLiaQMECBAIAuIZ0JwQIEBAPG2AAAECQUA8A5oTAgQIiKcNECBAIAiIZ0BzQoAAAfG0AQIECAQB8QxoTggQICCeNkCAAIEgIJ4BzQkBAgTE0wYIECAQBMQzoDkhQICAeNoAAQIEgoB4BjQnBAgQEE8bIECAQBAQz4DmhAABAuJpAwQIEAgC4hnQnBAgQEA8bYAAAQJBQDwDmhMCBAiIpw0QIEAgCIhnQHNCgAAB8bQBAgQIBAHxDGhOCBAgIJ42QIAAgSAgngHNCQECBMTTBggQIBAExDOgOSFAgIB42gABAgSCgHgGNCcECBAQTxsgQIBAEBDPgOaEAAEC4mkDBAgQCALiGdCcECBAQDxtgAABAkFAPAOaEwIECIinDRAgQCAIiGdAc0KAAAHxtAECBAgEAfEMaE4IECAgnjZAgACBICCeAc0JAQIExNMGCBAgEATEM6A5IUCAgHjaAAECBIKAeAY0JwQIEBBPGyBAgEAQEM+A5oQAAQLiaQMECBAIAuIZ0JwQIEBAPG2AAAECQUA8A5oTAgQIiKcNECBAIAiIZ0BzQoAAAfG0AQIECAQB8QxoTggQICCeNkCAAIEgIJ4BzQkBAgTE0wYIECAQBMQzoDkhQICAeNoAAQIEgoB4BjQnBAgQEE8bIECAQBAQz4DmhAABAuJpAwQIEAgC4hnQnBAgQEA8bYAAAQJBQDwDmhMCBAiIpw0QIEAgCIhnQHNCgAAB8bQBAgQIBAHxDGhOCBAgIJ42QIAAgSAgngHNCQECBMTTBggQIBAExDOgOSFAgIB42gABAgSCgHgGNCcECBAQTxsgQIBAEBDPgOaEAAEC4mkDBAgQCALiGdCcECBAQDxtgAABAkFAPAOaEwIECIinDRAgQCAIiGdAc0KAAAHxtAECBAgEAfEMaE4IECAgnjZAgACBIHABajmP8Afx1EQAAAAASUVORK5CYII="
  style={{ backgroundColor: '#f5f8ff' }}
  src="https://www.trillet.ai/videos/promo.mp4"
></video>

## Transform Customer Interactions with AI

Trillet AI provides a powerful REST API to create human-like voice and messaging experiences at scale. Our platform combines state-of-the-art language models with advanced voice synthesis to enable natural conversations across multiple channels.

<Columns cols={2}>
  <Card
    title="Quick Start"
    icon="rocket"
    href="/documentation/quickstart"
  >
    Set up your first agent in minutes!
  </Card>
  <Card
    title="API Reference"
    icon="code"
    href="/v1/api-reference/introduction"
  >
    Explore our comprehensive API documentation
  </Card>
</Columns>

## Core Features

<Columns cols={2}>
  <Card
    title="Call Agents API"
    icon="robot"
    href="/v1/api-reference/endpoints/agents/call/create"
  >
    Create and manage conversational call agents with unique voices and personalities through our REST API
  </Card>
  <Card
    title="Omni Flow Agents API"
    icon="message-bot"
    href="/v1/api-reference/endpoints/agents/omniflow/create"
  >
    Create and manage messaging AI agents with unique through our REST API
  </Card>
  <Card
    title="Call Flows API"
    icon="diagram-project"
    href="/v1/api-reference/endpoints/flows/call-flows/create"
  >
    Design and control call & conversation flows programmatically
  </Card>
  <Card
    title="Message Flows API"
    icon="message-code"
    href="/v1/api-reference/endpoints/flows/message-flows/create"
  >
    Design and control call & conversation flows programmatically
  </Card>
  <Card
    title="Voice Calls API"
    icon="phone"
    href="/v1/api-reference/endpoints/calls/initiate-call"
  >
    Initiate and manage voice calls via REST endpoints
  </Card>
  <Card
      title="Conversations API"
      icon="comments"
      href="/v1/api-reference/endpoints/conversations/generateMessage"
    >
    Design and control customer interactions through conversations programmatically
  </Card>
</Columns>

## Getting Started

1. Sign up for an API key at [app.trillet.ai](https://app.trillet.ai)
2. Follow our [Quick Start Guide](/documentation/quickstart) to make your first API call
3. Explore our [API Reference](/v1/api-reference/introduction) for detailed endpoint documentation

## Resources

<Columns cols={3}>
  <Card
    title="API Documentation"
    icon="book"
    href="/v1/api-reference/introduction"
  >
    Complete API reference
  </Card>
  <Card
    title="Best Practices"
    icon="star"
    href="/documentation/best-practices"
  >
    API integration guidelines
  </Card>
  <Card
    title="Support"
    icon="headset"
    href="mailto:support@trillet.ai"
  >
    Get technical help
  </Card>
</Columns>

---

## On-Premise Deployment

*Run Trillet in Your Own Infrastructure*

## On-Premise Deployment: Run Trillet in Your Own Infrastructure

Trillet is now available for on-premise deployment. For enterprises that need complete control over where their data lives, you can run our full voice AI platform within your own infrastructure.

**Trillet is the only voice AI orchestration and application platform in Australia offering on-premise deployment.**

## Why On-Premise?

### Data Sovereignty
Customer conversations never leave your controlled environment. For Australian companies operating under strict regulatory requirements, this simplifies compliance and gives your security team full visibility over where sensitive data resides.

### Privacy
Voice interactions contain highly personal information. On-premise deployment ensures that customer calls, account details, and sensitive data stay within your perimeter, not traversing third-party networks.

### Compliance
Whether you're navigating APRA CPS 234, HIPAA, or internal security policies, on-premise deployment provides the audit trail and control you need to satisfy regulators and stakeholders.

### Performance
Running locally eliminates network latency to external providers, delivering faster response times for your customers.

## What's Included

Trillet ships as a Docker container that includes our complete platform: the orchestration layer, API management, and management UI. You're not just getting an inference engine, you're getting the full application.

**Bring your own providers.** Trillet orchestrates your choice of TTS, LLM, and telephony components, including on-premise models from providers that offer them. You control the stack.

## Who It's For

On-premise deployment is designed for Australian enterprises with strict data sovereignty requirements. If your security policies require that customer voice data stays within infrastructure you control, or if you operate in regulated industries where compliance demands are high, on-premise is for you.

## Still Fully Managed

On-premise doesn't mean DIY. Our team handles deployment, configuration, updates, and ongoing support. You get the compliance posture of on-premise with the operational simplicity of a managed service.

## Get Started

To discuss on-premise deployment for your organisation, [contact our sales team](https://cal.com/forms/1feb42e7-a4b2-4cd3-8076-18ea016b1a2f).

---

## documentation/platform-integrations

## Trillet AI Integrations
Trillet AI offers seamless integration with popular automation tools like **Make.com**, **n8n**, and our **Web SDK**, allowing you to automate **outbound AI voice calls** and embed **AI agents directly into your applications**. Use these platforms and tools to trigger TrilletAI's call capabilities directly from your workflows or integrate voice agents into your websites.

---

## Make.com Integration
<img
  className="hidden h-32 dark:block"
  src="../logo/make-color.png"
  alt="Hero Dark"
/>
<img
  className="block h-32 dark:hidden"
  src="../logo/make-color.png"
  alt="Hero Light"
/>

Integrate Trillet AI with Make.com **custom node** to automate **outbound voice call workflows**. This is ideal for building call-based campaigns, customer notifications, or voice follow-ups powered by Trillet AI.

### Installation

To add TrilletAI's app to your Make.com organization:

You can find TrilletAI directly on Make.com by searching **"TrilletAI"** in the App list under the `us1` or `us2` regions.

If TrilletAI does not appear in your region or account, use the invitation link below to add it manually:

🔗 **[Click here to install](https://www.make.com/en/hq/app-invitation/380f3212527664bd958eb3bf383c97fe)** if it doesn't appear.

## n8n Integration
<img
  className="hidden h-32 dark:block"
  src="../logo/n8n-color.png"
  alt="Hero Dark"
/>
<img
  className="block h-32 dark:hidden"
  src="../logo/n8n-color.png"
  alt="Hero Light"
/>

TrilletAI provides a **custom node** for [n8n](https://n8n.io) to let you trigger **outbound voice calls** directly within your workflows. This allows you to automate call-based sequences based on custom events, user actions, or external system triggers.

### Installation Steps

1. Ensure `n8n` is installed on your machine. If not, follow [n8n installation guide](https://docs.n8n.io/).
2. Open your terminal and install the TrilletAI node package:

```bash
npm install n8n-trillet-nodes
```

---

## SDK Integration
<img
  className="hidden h-32 dark:block"
  src="../logo/sdk-logo.png"
  alt="Hero Dark"
/>
<img
  className="block h-32 dark:hidden"
  src="../logo/sdk-logo.png"
  alt="Hero Light"
/>

The Trillet AI Web SDK allows you to integrate **AI-powered voice agents** directly into your website or web application. This enables users to interact with your Trillet AI agents via voice or text calls, ideal for embedding real-time AI conversations in client-facing apps, demos, or custom workflows. The SDK uses LiveKit for real-time audio handling and supports features like transcription, audio analysis, and event emitting.

### Installation

You can install the SDK via npm for modern web frameworks (e.g., React, Next.js) or load it directly from a CDN for simple HTML integrations.

#### Via npm
1. Install the package:

```bash
npm install @trillet-ai/web-sdk
```

2. Import and use in your code:

```typescript
import { TrilletAgent } from '@trillet-ai/web-sdk';
```

#### Via CDN (No Build Tools Required)
Include the SDK script in your HTML:

```html
<script type="module">
  const module = await import("https://cdn.jsdelivr.net/npm/@trillet-ai/web-sdk/+esm");
  const TrilletAgent = module.TrilletAgent;
  // Use TrilletAgent here
</script>
```

**Note:** The SDK requires a browser environment with secure context (HTTPS or localhost). It does not support server-side rendering.

### Configuration
Initialize a `TrilletAgent` instance:

```typescript
const agent = new TrilletAgent({
  workspaceId: 'your-workspace-id',
  agentId: 'your-agent-id',
  variables: { key: 'value' },
  mode: 'voice',
});
```

### Usage
1. **Start a Call:**
   - Use `startPublicCall()` for public (workspace-based) integrations.
   - Use `startCall()` for API key authenticated calls.

```typescript
try {
  await agent.startPublicCall();
  console.log('Call started');
} catch (error) {
  console.error('Failed to start call:', error);
}
```

2. **End a Call:**

```typescript
agent.endCall();
```

3. **Toggle Microphone:**

```typescript
agent.toggleMicrophone(true); // Enable microphone
```

4. **Event Handling:**
   The SDK extends `EventEmitter`. Listen for events like `connected`, `disconnected`, `error`, `assistantStartedSpeaking`, etc.

```typescript
agent.on('connected', (details) => {
  console.log('Connected:', details.callId, details.agent.name);
});

agent.on('disconnected', () => {
  console.log('Call ended');
});

agent.on('error', (error) => {
  console.error('Error:', error);
});
```

5. **Transcripts:**
   Access real-time and final transcripts:

```typescript
const transcripts = agent.getTranscripts(); // Array of Transcript objects
const current = agent.getCurrentTranscript(); // Partial transcripts
```

### SDK Integration Preview

<img
  className="block w-full max-w-md mx-auto rounded-lg"
  src="../logo/sdk.png"
  alt="Trillet AI SDK Integration"
/>

<Note>
  **Important:** Make sure to enable public access in your call flow settings before testing the SDK integration. You can find this option in the call flow settings panel.
</Note>

### Examples

#### React Component Integration
For React/Next.js apps, create a basic component to handle calls:

```tsx
import { useState, useRef } from 'react';
import { TrilletAgent } from '@trillet-ai/web-sdk';

const VoiceAgent = ({ agentId, workspaceId }) => {
  const agentRef = useRef(null);
  const [isCallActive, setIsCallActive] = useState(false);

  if (!agentRef.current) {
    agentRef.current = new TrilletAgent({
      workspaceId,
      agentId,
    });
  }

  const startCall = async () => {
    try {
      await agentRef.current.startPublicCall();
      setIsCallActive(true);
    } catch (error) {
      console.error('Failed to start call:', error);
    }
  };

  const endCall = () => {
    agentRef.current.endCall();
    setIsCallActive(false);
  };

  return (
    <button onClick={isCallActive ? endCall : startCall}>
      {isCallActive ? 'Hang Up' : 'Start Call'}
    </button>
  );
};

export default VoiceAgent;
```

#### Simple HTML Button Integration
Embed a button that starts/stops a voice call with your agent:

```html
<!-- Trillet Voice Button -->
<style>
  #trillet-voice-button {
    padding: 14px 28px;
    font-size: 16px;
    font-weight: bold;
    background: linear-gradient(to right, #25aae1, #40e495, #30dd8a, #2bb673);
    color: white;
    border: none;
    border-radius: 50px;
    cursor: pointer;
    z-index: 999;
    box-shadow: 0 8px 20px rgba(0, 102, 255, 0.4);
    transition: all 0.3s ease;
  }

  #trillet-voice-button:hover {
    transform: scale(1.05);
  }
</style>

<button id="trillet-voice-button">
  🎙️ Speak with AI Agent
</button> 

<script type="module">
  const { TrilletAgent } = await import("https://cdn.jsdelivr.net/npm/@trillet-ai/web-sdk/+esm");

  const workspaceId = "your-workspace-id"; // Replace with your workspace ID
  const agentId = "your-agent-id"; // Replace with your agent ID
  const button = document.getElementById("trillet-voice-button");

  const agent = new TrilletAgent({ workspaceId, agentId });
  let isCalling = false;

  button.addEventListener("click", async () => {
    if (!isCalling) {
      try {
        button.innerText = "⏳ Connecting...";
        button.disabled = true;
        await agent.startPublicCall();
        isCalling = true;
        button.innerText = "Hang Up 🔴";
      } catch (err) {
        console.error("Failed to start call:", err);
        alert("Could not start the AI call. Please try again.");
        button.innerText = "🎙️ Speak with AI Agent";
      } finally {
        button.disabled = false;
      }
    } else {
      agent.endCall();
      isCalling = false;
      button.innerText = "🎙️ Speak with AI Agent";
    }
  });

  agent.on("disconnected", () => {
    isCalling = false;
    button.innerText = "🎙️ Speak with AI Agent";
    button.disabled = false;
  });
</script>
```

**Note:** Replace placeholders like `your-workspace-id` and `your-agent-id` with your actual Trillet AI credentials. For production, secure sensitive data (e.g., avoid exposing API keys client-side). The SDK handles browser compatibility checks internally. If you encounter issues, ensure microphone permissions are granted and test in a secure context.

---

## Quickstart Guide

*Complete guide to setting up your first AI agent in Trillet - from creating call flows to handling live calls*

This handbook walks you through setting up your first AI agent in Trillet. From creating call flows to assigning numbers and handling live calls, you'll learn each step to get your agent running smoothly.

<Note>
**Ready to scale beyond the basics?** Our platform supports complete white-label customization - imagine your own branded domain, custom email notifications, and workspaces that reflect your unique brand identity. Perfect for agencies and enterprises looking to offer AI voice solutions under their own name. [Explore Whitelabel](https://app.trillet.ai/settings) to unlock unlimited branding possibilities.
</Note>

<Tip>
Looking for advanced whitelabel features? Our [Exclusive Whitelabel Guide](https://app.trillet.ai/) contains premium strategies and configurations - available exclusively to Whitelabel subscribers.
</Tip>

## Getting Started

Once you sign in, you'll land on your Home Page. To build an AI agent, the first step is creating a Call Flow.

1. **Access the Side Panel**: Hover over and click the Trillet logo. This will open the Side Panel.

<img
  className="block dark:hidden rounded-xl"
  src="../images/sidebar.png"
  alt="Sidebar Interface"
/>
<img
  className="hidden dark:block rounded-xl"
  src="/images/dark/sidebar.png"
  alt="Sidebar Interface"
/>

2. **Navigate the Interface**: From the Side Panel, you can navigate to all sections of the Trillet interface. Each section has its own functionality, which we'll explore as we move through this handbook.

3. **Start with Flow Studio**: 
   - In the Side Panel, click **Flow Studio**
   - This will open a dropdown menu with two options: [Call Flows](/v1/api-reference/endpoints/flows/call-flows/create) and [Message Flows](/v1/api-reference/endpoints/flows/message-flows/create)

4. **Choose Your Flow Type**: Trillet lets you create both, depending on your use case. In this module, we'll start with a Call Flow.

### Understanding Call Flows

A Call Flow is the backbone of your AI agent. It defines how conversations are structured and whether your agent will handle one-way or two-way communication. You can think of it like a blueprint for your agent's calls.

After navigating to Call Flows, your dashboard will look like this:

<img
  className="block dark:hidden rounded-xl"
  src="../images/call_flows_page.png"
  alt="Call Flows Dashboard"
/>
<img
  className="hidden dark:block rounded-xl"
  src="/images/dark/call_flows_page.png"
  alt="Call Flows Dashboard"
/>

- As you create call flows, they'll appear here for quick access
- You can also add personal folders to keep your work organized

To begin building your first flow, click the **Create New Flow** button.

## 1.1 Create a Call Flow from Scratch

Trillet gives you the ability to customize your agent and choose how it communicates with users.

On this page, you'll set the foundation for your AI agent by giving it a name, defining its purpose, and selecting the right call direction, voice, and language model. Think of this as your agent's "identity card" - the details you set here define how it looks, sounds, and behaves during conversations.

<img
  className="block dark:hidden rounded-xl"
  src="../images/call_flow_creation.png"
  alt="Call Flow Creation Interface"
/>
<img
  className="hidden dark:block rounded-xl"
  src="/images/dark/call_flow_creation.png"
  alt="Call Flow Creation Interface"
/>

### Configuration Steps

**Select Folder**
- Choose the folder where you want to save this call flow
- Organizing flows into folders helps keep your workspace tidy

**Enter Flow Information**
- **Flow Title**: Give your call flow a descriptive name (e.g., Sales Demo Flow)
- **Description**: Add a short explanation of what this flow is for (optional, but useful if you have multiple flows)
- **Call Direction**:
  - **Outbound Only**: one-way outgoing calls without return calls
  - **Outbound & Inbound**: two-way conversations where the agent can also receive calls

Select the option that matches your use case.

**Configure Your Agent**
- **Agent Name**: Assign a name to your agent. This is how it will appear across your workspace
- **Language Model**: Select the AI model that powers your agent's responses (see [Call Agents API](/v1/api-reference/endpoints/agents/call/create) for available models)
- **Voice Options**: Choose from available voices:
  - Trillet AI Voices (default, included)
  - ElevenLabs Voices (premium, additional cost)
  - BYO ElevenLabs (bring your own ElevenLabs account) [You will need to ensure that you have added the voices to your ElevenLabs account first under 'My Voices' and that the necessary privileges are provided to the API key.]
- **Flow Generator**: Trillet gives you the ability to turn an existing call recording into a ready-to-use call flow

Once you've filled in the details, click **Next** (bottom right) to move on to prompting your agent.

## 1.2 Prompting Your Agent

The way you prompt your agent determines how well it performs during conversations. Think of it like giving instructions to a teammate before they step into a meeting - the clearer and more specific you are, the better they'll handle the interaction.

You can also choose how your agent starts off the call — whether that's waiting for the caller to speak first, using an AI-generated greeting that adapts to context, or delivering a custom greeting you've written yourself.

<img
  className="block dark:hidden rounded-xl"
  src="../images/prompt_editor.png"
  alt="Prompt Editor Interface"
/>
<img
  className="hidden dark:block rounded-xl"
  src="/images/dark/prompt_editor.png"
  alt="Prompt Editor Interface"
/>

### Writing Effective Prompts

A strong prompt usually includes:
- **A clear goal** → what is the agent trying to achieve on this call?
- **Background context** → who is the agent, and what key details should they know?
- **Conversation flow** → the step-by-step path the agent should follow to reach the goal

### Using the Prompt Template

To make this easier, Trillet provides a prompt template you can follow. Instead of starting from scratch, the template gives you a ready-made structure that covers all the essentials: defining your agent's role, setting formatting rules, and mapping out the conversation flow.

**Example Prompt Structure:**
If your agent's goal is to qualify leads for a demo, your prompt might:
- Set the goal as confirming interest and booking a demo slot
- Provide background context like "You are Alex, a friendly sales assistant from Acme Software"
- Outline a conversation flow where the agent greets the lead, confirms their availability, and suggests two demo times

### Testing Your Agent

    You can test your agent through both **Voice Chat** and **Text Chat**. **Voice Chat** lets you experience how it sounds in a live call, while **Text Chat** makes it easy to review responses in writing. Both methods allow you to fine-tune your prompt and improve the agent's performance.

<div className="flex flex-col lg:flex-row items-start gap-6">
  <div className="flex-shrink-0">
    <img
      className="block dark:hidden rounded-xl"
      src="../images/save_and_test_button.png"
      alt="Save & Test Agent Button"
    />
    <img
      className="hidden dark:block rounded-xl"
      src="/images/dark/save_and_test_button.png"
      alt="Save & Test Agent Button"
    />
  </div>
  <div className="flex-1">
    <p>
    When you're ready to test, click the **Save & Test Agent** button in the top-right corner of the prompt editor.
    </p>
  </div>
</div>

    You can test your agent through both **Voice Chat** and **Text Chat**:

<div className="flex flex-col lg:flex-row items-start gap-6">
  <div className="flex-shrink-0">
    <img
      className="block dark:hidden rounded-xl"
      src="../images/test_agent.png"
      alt="Test Agent Interface"
    />
    <img
      className="hidden dark:block rounded-xl"
      src="/images/dark/test_agent.png"
      alt="Test Agent Interface"
    />
  </div>
  <div className="flex-1">
    <p>
    - **Voice Chat** lets you experience how it sounds in a live call
    - **Text Chat** makes it easy to review responses in writing

    Both methods allow you to fine-tune your prompt and improve the agent's performance.
    </p>
  </div>
</div>

<Note>
It's always a good idea to test your prompt with different variations to see what gives you the most natural results.
</Note>

## 1.3 Assigning a Phone Number

When you're ready to take your AI agent live, it needs a phone number that people can call. Assigning a number is what connects your agent to the outside world, allowing it to handle real conversations instead of just test runs.

<img
  className="block dark:hidden rounded-xl"
  src="../images/phone_number_page.png"
  alt="Phone Number Management"
/>
<img
  className="hidden dark:block rounded-xl"
  src="/images/dark/phone_number_page.png"
  alt="Phone Number Management"
/>

### Number Options

Trillet gives you two options:

**1. Buy a New Number**
- Purchase directly through the platform
- Quick setup and ready to use right away
- Search by country, type (local or toll-free), state, or area code

<img
  className="block dark:hidden rounded-xl"
  src="../images/number_purchase.png"
  alt="Number Purchase Interface"
/>
<img
  className="hidden dark:block rounded-xl"
  src="/images/dark/number_purchase.png"
  alt="Number Purchase Interface"
/>

**2. Bring Your Own Number**
- Link an existing number from providers like Twilio
- Keep using your existing carrier rates
- Manage everything from within Trillet

<img
  className="block dark:hidden rounded-xl"
  src="../images/bring_your_own_number.png"
  alt="Bring Your Own Number"
/>
<img
  className="hidden dark:block rounded-xl"
  src="/images/dark/bring_your_own_number.png"
  alt="Bring Your Own Number"
/>

### Number Assignment

Once you have a number, you can assign it to your AI agent:

<img
  className="block dark:hidden rounded-xl"
  src="../images/number_assignment.png"
  alt="Number Assignment Interface"
/>
<img
  className="hidden dark:block rounded-xl"
  src="/images/dark/number_assignment.png"
  alt="Number Assignment Interface"
/>

Configuration options include:
- Choose whether to assign to a call or message flow
- Select the agent it should connect with
- Enable call recording
- Add metadata tags for dynamic interactions

### Next Steps After Assignment

Once your number is linked, you can configure:
- Maximum call duration
- Call recording settings
- Business hours
- Call or Message flow assignment

When everything is configured, your number is live and ready. Make a quick test call to confirm everything works as expected.

## 1.4 Sending and Receiving Calls

Once a phone number is assigned to your AI agent, you can configure how it handles incoming and outgoing calls.

### Single Calls

To assign a single number: go to **Sidebar → Calls → Single Call**

Simply select the agent you want to map the number to (the same agent you assigned the phone number to) and enter the number where you'd like to receive the calls.

You can also use our [Voice Calls API](/v1/api-reference/endpoints/calls/initiate-call) to programmatically initiate calls:

```bash
curl -X POST https://api.trillet.ai/api/v1/calls/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your_agent_id",
    "toNumber": "+1234567890",
    "fromNumber": "your_assigned_number"
  }'
```

### Batch Calls

Trillet also gives you the ability to place batch calls. To access this feature: **Sidebar → Calls → Batch Calls**

Batch Calls let you reach multiple contacts at once instead of dialing them individually. This is especially helpful for:
- Lead reactivation campaigns
- Appointment reminders
- Survey collection
- Follow-up calls

**Setup Process:**
1. Select an agent
2. Upload a CSV file with contact details
3. Schedule when the calls should go out
4. Review past batches under "View History" to track performance

<Tip>
For large-scale operations, consider using our [Batch Calls API](/v1/api-reference/endpoints/calls/batch/overview) to programmatically manage batch calls and monitor their status.
</Tip>

## 1.5 Setting up Transfers

Transfers let your agent hand a call over to a real person or another system when needed. This is useful for situations where the conversation requires human support, a specialized team, or a different department.

<img
  className="block dark:hidden rounded-xl"
  src="../images/transfer.png"
  alt="Transfer Configuration"
/>
<img
  className="hidden dark:block rounded-xl"
  src="/images/dark/transfer.png"
  alt="Transfer Configuration"
/>

### Transfer Setup Steps

1. **Click Add New Transfer**
2. **Enter a friendly name** (e.g., Support Team)
3. **Select the transfer type**
4. **Choose the destination type** (Phone Number/SIP Address or Phone Metadata Tags)
5. **Enter the destination** in the valid format:
   - Phone: `+12025550123`
   - SIP: `sip:user@domain.com`
6. **Save your transfer** - your agent will now know where to route calls when triggered

### Transfer Types

- **Warm Transfer**: Agent stays on the line during handoff
- **Cold Transfer**: Agent immediately transfers and disconnects

<Warning>
Make sure to test your transfer destinations to ensure they're properly configured and accessible.
</Warning>

## API Integration

Throughout this guide, we've focused on the visual interface, but every feature is also available through our comprehensive REST API:

<Columns cols={2}>
  <Card
    title="Call Agents API"
    icon="robot"
    href="/v1/api-reference/endpoints/agents/call/create"
  >
    Create and manage conversational agents programmatically
  </Card>
  <Card
    title="Call Flows API"
    icon="diagram-project"
    href="/v1/api-reference/endpoints/flows/call-flows/create"
  >
    Design conversation flows via API
  </Card>
  <Card
    title="Voice Calls API"
    icon="phone"
    href="/v1/api-reference/endpoints/calls/initiate-call"
  >
    Initiate and manage calls programmatically
  </Card>
  <Card
    title="Conversations API"
    icon="comments"
    href="/v1/api-reference/endpoints/conversations/generateMessage"
  >
    Handle real-time conversations
  </Card>
</Columns>

## Next Steps

Now that you've set up your first AI agent, explore these advanced features:

<Columns cols={2}>
  <Card
    title="Exclusive Whitelabel Guide"
    icon="building"
    href="https://app.trillet.ai/"
  >
    Scale your implementation with whitelabel tools
  </Card>
  <Card
    title="Analytics & Monitoring"
    icon="chart-line"
    href="https://app.trillet.ai/calls/analytics"
  >
    Track performance and optimize your agents
  </Card>
  <Card
    title="Advanced Prompting [Soon!]"
    icon="wand-magic-sparkles"
  >
    Learn advanced prompting techniques for better conversations
  </Card>
  <Card
    title="Platform Integrations"
    icon="webhook"
    href="/platform-integrations"
  >
    Connect your agent to external systems
  </Card>
</Columns>

## Support & Resources

<Columns cols={3}>
  <Card
    title="API Documentation"
    icon="book"
    href="/v1/api-reference/introduction"
  >
    Complete API reference and examples
  </Card>
  <Card
    title="Community"
    icon="users"
    href="https://www.skool.com/trillet-ai"
  >
    Join our developer community
  </Card>
  <Card
    title="Support"
    icon="headset"
    href="https://app.trillet.ai/support-plans"
  >
    Get a support plan for direct technical help and guidance
  </Card>
</Columns>

---

## Code Blocks

*Display inline code and code blocks*

## Basic

### Inline Code

To denote a `word` or `phrase` as code, enclose it in backticks (`).

```
To denote a `word` or `phrase` as code, enclose it in backticks (`).
```

### Code Block

Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.

```java HelloWorld.java
class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
```

````md
```java HelloWorld.java
class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
```
````

---

## Images and Embeds

*Add image, video, and other HTML elements*

<img
  style={{ borderRadius: '0.5rem' }}
  src="https://mintlify-assets.b-cdn.net/bigbend.jpg"
/>

## Image

### Using Markdown

The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code

```md
![title](/path/image.jpg)
```

Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.

### Using Embeds

To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images

```html
<img height="200" src="/path/image.jpg" />
```

## Embeds and HTML elements

<iframe
  className="w-full aspect-video rounded-xl"
  src="https://www.youtube.com/embed/4KzFe50RQkQ"
  title="YouTube video player"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
/>

<br />

<Tip>

Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.

</Tip>

### iFrames

Loads another HTML page within the document. Most commonly used for embedding videos.

```html
<iframe
  className="w-full aspect-video rounded-xl"
  src="https://www.youtube.com/embed/4KzFe50RQkQ"
  title="YouTube video player"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
/>
```

---

## Markdown Syntax

*Text, title, and styling in standard markdown*

## Titles

Best used for section headers.

```md
## Titles
```

### Subtitles

Best use to subsection headers.

```md
### Subtitles
```

<Tip>

Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right.

</Tip>

## Text Formatting

We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.

| Style         | How to write it   | Result          |
| ------------- | ----------------- | --------------- |
| Bold          | `**bold**`        | **bold**        |
| Italic        | `_italic_`        | _italic_        |
| Strikethrough | `~strikethrough~` | ~strikethrough~ |

You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text.

You need to use HTML to write superscript and subscript text. That is, add `<sup>` or `<sub>` around your text.

| Text Size   | How to write it          | Result                 |
| ----------- | ------------------------ | ---------------------- |
| Superscript | `<sup>superscript</sup>` | <sup>superscript</sup> |
| Subscript   | `<sub>subscript</sub>`   | <sub>subscript</sub>   |

## Linking to Pages

You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).

Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section.

Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.

## Blockquotes

### Singleline

To create a blockquote, add a `>` in front of a paragraph.

> Dorothy followed her through many of the beautiful rooms in her castle.

```md
> Dorothy followed her through many of the beautiful rooms in her castle.
```

### Multiline

> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

```md
> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
```

### LaTeX

Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component.

<Latex>8 x (vk x H1 - H2) = (0,1)</Latex>

```md
<Latex>8 x (vk x H1 - H2) = (0,1)</Latex>
```

---

## Navigation

*The navigation field in mint.json defines the pages that go in the navigation menu*

The navigation menu is the list of links on every website.

You will likely update `mint.json` every time you add a new page. Pages do not show up automatically.

## Navigation syntax

Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names.

<CodeGroup>

```json Regular Navigation
"navigation": [
    {
        "group": "Getting Started",
        "pages": ["quickstart"]
    }
]
```

```json Nested Navigation
"navigation": [
    {
        "group": "Getting Started",
        "pages": [
            "quickstart",
            {
                "group": "Nested Reference Pages",
                "pages": ["nested-reference-page"]
            }
        ]
    }
]
```

</CodeGroup>

## Folders

Simply put your MDX files in folders and update the paths in `mint.json`.

For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`.

<Warning>

You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted.

</Warning>

```json Navigation With Folder
"navigation": [
    {
        "group": "Group Name",
        "pages": ["your-folder/your-page"]
    }
]
```

## Hidden Pages

MDX files not included in `mint.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them.

---

## Reusable Snippets

*Reusable, custom snippets to keep content in sync*

import SnippetIntro from '/snippets/snippet-intro.mdx';

<SnippetIntro />

## Creating a custom snippet

**Pre-condition**: You must create your snippet file in the `snippets` directory.

<Note>
  Any page in the `snippets` directory will be treated as a snippet and will not
  be rendered into a standalone page. If you want to create a standalone page
  from the snippet, import the snippet into another file and call it as a
  component.
</Note>

### Default export

1. Add content to your snippet file that you want to re-use across multiple
   locations. Optionally, you can add variables that can be filled in via props
   when you import the snippet.

```mdx snippets/my-snippet.mdx
Hello world! This is my content I want to reuse across pages. My keyword of the
day is {word}.
```

<Warning>
  The content that you want to reuse must be inside the `snippets` directory in
  order for the import to work.
</Warning>

2. Import the snippet into your destination file.

```mdx destination-file.mdx
---
title: My title
description: My Description
---

import MySnippet from '/snippets/path/to/my-snippet.mdx';

## Header

Lorem impsum dolor sit amet.

<MySnippet word="bananas" />
```

### Reusable variables

1. Export a variable from your snippet file:

```mdx snippets/path/to/custom-variables.mdx
export const myName = 'my name';

export const myObject = { fruit: 'strawberries' };
```

2. Import the snippet from your destination file and use the variable:

```mdx destination-file.mdx
---
title: My title
description: My Description
---

import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';

Hello, my name is {myName} and I like {myObject.fruit}.
```

### Reusable components

1. Inside your snippet file, create a component that takes in props by exporting
   your component in the form of an arrow function.

```mdx snippets/custom-component.mdx
export const MyComponent = ({ title }) => (
  <div>
    <h1>{title}</h1>
    <p>... snippet content ...</p>
  </div>
);
```

<Warning>
  MDX does not compile inside the body of an arrow function. Stick to HTML
  syntax when you can or use a default export if you need to use MDX.
</Warning>

2. Import the snippet into your destination file and pass in the props

```mdx destination-file.mdx
---
title: My title
description: My Description
---

import { MyComponent } from '/snippets/custom-component.mdx';

Lorem ipsum dolor sit amet.

<MyComponent title={'Custom title'} />
```

---

## Global Settings

*Mintlify gives you complete control over the look and feel of your documentation using the mint.json file*

Every Mintlify site needs a `mint.json` file with the core configuration settings. Learn more about the [properties](#properties) below.

## Properties

<ResponseField name="name" type="string" required>
Name of your project. Used for the global title.

Example: `mintlify`

</ResponseField>

<ResponseField name="navigation" type="Navigation[]" required>
  An array of groups with all the pages within that group
  <Expandable title="Navigation">
    <ResponseField name="group" type="string">
    The name of the group.

    Example: `Settings`

    </ResponseField>
    <ResponseField name="pages" type="string[]">
    The relative paths to the markdown files that will serve as pages.

    Example: `["customization", "page"]`

    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="logo" type="string or object">
  Path to logo image or object with path to "light" and "dark" mode logo images
  <Expandable title="Logo">
    <ResponseField name="light" type="string">
      Path to the logo in light mode
    </ResponseField>
    <ResponseField name="dark" type="string">
      Path to the logo in dark mode
    </ResponseField>
    <ResponseField name="href" type="string" default="/">
      Where clicking on the logo links you to
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="favicon" type="string">
  Path to the favicon image
</ResponseField>

<ResponseField name="colors" type="Colors">
  Hex color codes for your global theme
  <Expandable title="Colors">
    <ResponseField name="primary" type="string" required>
      The primary color. Used for most often for highlighted content, section
      headers, accents, in light mode
    </ResponseField>
    <ResponseField name="light" type="string">
      The primary color for dark mode. Used for most often for highlighted
      content, section headers, accents, in dark mode
    </ResponseField>
    <ResponseField name="dark" type="string">
      The primary color for important buttons
    </ResponseField>
    <ResponseField name="background" type="object">
      The color of the background in both light and dark mode
      <Expandable title="Object">
        <ResponseField name="light" type="string" required>
          The hex color code of the background in light mode
        </ResponseField>
        <ResponseField name="dark" type="string" required>
          The hex color code of the background in dark mode
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="topbarLinks" type="TopbarLink[]">
  Array of `name`s and `url`s of links you want to include in the topbar
  <Expandable title="TopbarLink">
    <ResponseField name="name" type="string">
    The name of the button.

    Example: `Contact us`
    </ResponseField>
    <ResponseField name="url" type="string">
    The url once you click on the button. Example: `https://mintlify.com/docs`
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="topbarCtaButton" type="Call to Action">
  <Expandable title="Topbar Call to Action">
    <ResponseField name="type" type={'"link" or "github"'} default="link">
    Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars.
    </ResponseField>
    <ResponseField name="url" type="string">
    If `link`: What the button links to.
    
    If `github`: Link to the repository to load GitHub information from.
    </ResponseField>
    <ResponseField name="name" type="string">
    Text inside the button. Only required if `type` is a `link`.
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="versions" type="string[]">
  Array of version names. Only use this if you want to show different versions
  of docs with a dropdown in the navigation bar.
</ResponseField>

<ResponseField name="anchors" type="Anchor[]">
  An array of the anchors, includes the `icon`, `color`, and `url`.
  <Expandable title="Anchor">
    <ResponseField name="icon" type="string">
    The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor.

    Example: `comments`
    </ResponseField>
    <ResponseField name="name" type="string">
    The name of the anchor label.

    Example: `Community`
    </ResponseField>
    <ResponseField name="url" type="string">
      The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
    </ResponseField>
    <ResponseField name="color" type="string">
      The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color.
    </ResponseField>
    <ResponseField name="version" type="string">
      Used if you want to hide an anchor until the correct docs version is selected.
    </ResponseField>
    <ResponseField name="isDefaultHidden" type="boolean" default="false">
      Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
    </ResponseField>
    <ResponseField name="iconType" default="duotone" type="string">
      One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="topAnchor" type="Object">
  Override the default configurations for the top-most anchor.
  <Expandable title="Object">
    <ResponseField name="name" default="Documentation" type="string">
      The name of the top-most anchor
    </ResponseField>
    <ResponseField name="icon" default="book-open" type="string">
      Font Awesome icon.
    </ResponseField>
    <ResponseField name="iconType" default="duotone" type="string">
      One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tabs" type="Tabs[]">
  An array of navigational tabs.
  <Expandable title="Tabs">
    <ResponseField name="name" type="string">
      The name of the tab label.
    </ResponseField>
    <ResponseField name="url" type="string">
      The start of the URL that marks what pages go in the tab. Generally, this
      is the name of the folder you put your pages in.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="api" type="API">
  Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo).
  <Expandable title="API">
    <ResponseField name="baseUrl" type="string">
      The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url
      options that the user can toggle.
    </ResponseField>

    <ResponseField name="auth" type="Auth">
      <Expandable title="Auth">
        <ResponseField name="method" type='"bearer" | "basic" | "key"'>
          The authentication strategy used for all API endpoints.
        </ResponseField>
        <ResponseField name="name" type="string">
        The name of the authentication parameter used in the API playground.

        If method is `basic`, the format should be `[usernameName]:[passwordName]`
        </ResponseField>
        <ResponseField name="inputPrefix" type="string">
        The default value that's designed to be a prefix for the authentication input field.

        E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="playground" type="Playground">
      Configurations for the API playground

      <Expandable title="Playground">
        <ResponseField name="mode" default="show" type='"show" | "simple" | "hide"'>
          Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`

          Learn more at the [playground guides](/api-playground/demo)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="maintainOrder" type="boolean">
      Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file.

      <Warning>This behavior will soon be enabled by default, at which point this field will be deprecated.</Warning>
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="openapi" type="string | string[]">
  A string or an array of strings of URL(s) or relative path(s) pointing to your
  OpenAPI file.
  
  Examples:
  <CodeGroup>
    ```json Absolute
    "openapi": "https://example.com/openapi.json"
    ```
    ```json Relative
    "openapi": "/openapi.json"
    ```
    ```json Multiple
    "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
    ```
  </CodeGroup>

</ResponseField>

<ResponseField name="footerSocials" type="FooterSocials">
  An object of social media accounts where the key:property pair represents the social media platform and the account url.
  
  Example: 
  ```json
  {
    "x": "https://x.com/mintlify",
    "website": "https://mintlify.com"
  }
  ```
  <Expandable title="FooterSocials">
    <ResponseField name="[key]" type="string">
    One of the following values `website`, `facebook`, `x`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`
    
    Example: `x`
    </ResponseField>
    <ResponseField name="property" type="string">
    The URL to the social platform.
    
    Example: `https://x.com/mintlify`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="feedback" type="Feedback">
  Configurations to enable feedback buttons

  <Expandable title="Feedback">
    <ResponseField name="suggestEdit" type="boolean" default="false">
    Enables a button to allow users to suggest edits via pull requests
    </ResponseField>
    <ResponseField name="raiseIssue" type="boolean" default="false">
    Enables a button to allow users to raise an issue about the documentation
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="modeToggle" type="ModeToggle">
  Customize the dark mode toggle.
  <Expandable title="ModeToggle">
    <ResponseField name="default" type={'"light" or "dark"'}>
      Set if you always want to show light or dark mode for new users. When not
      set, we default to the same mode as the user's operating system.
    </ResponseField>
    <ResponseField name="isHidden" type="boolean" default="false">
      Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example:
      
      <CodeGroup>
      ```json Only Dark Mode
      "modeToggle": {
        "default": "dark",
        "isHidden": true
      }
      ```

      ```json Only Light Mode
      "modeToggle": {
        "default": "light",
        "isHidden": true
      }
      ```
      </CodeGroup>

    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="backgroundImage" type="string">
  A background image to be displayed behind every page. See example with
  [Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io).
</ResponseField>

---

## Code Blocks

*Fenced code blocks with automatic syntax highlighting, optional file titles, and CodeGroup for multi-language examples side by side.*

Fenced code blocks are automatically syntax-highlighted.

## Basic code block

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Add a language identifier after the opening fence for syntax highlighting:

````mdx
```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```
````

## With title

Add a title after the language:

```javascript server.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello World');
});

app.listen(3000);
```

````mdx
```javascript server.js
const express = require('express');
// ...
```
````

## Code groups

Show the same example in multiple languages:

<CodeGroup>
```javascript Node.js
const response = await fetch('https://api.example.com/data');
const data = await response.json();
```

```python Python
import requests
response = requests.get('https://api.example.com/data')
data = response.json()
```

```bash cURL
curl -X GET https://api.example.com/data
```
</CodeGroup>

````mdx
<CodeGroup>
```javascript Node.js
const response = await fetch('https://api.example.com/data');
```

```python Python
response = requests.get('https://api.example.com/data')
```
</CodeGroup>
````

---

## Components

*Built-in MDX components for your documentation pages — cards, callouts, tabs, steps, accordions, and code groups. No imports needed.*

Jamdesk includes built-in components that you can use directly in your MDX files. No imports needed.

## Available components

| Component | Use for |
|-----------|---------|
| **Card** | Highlighting features, linking to pages |
| **Columns** | Grid layouts of cards |
| **Callout** | Notes, tips, warnings |
| **Tabs** | Showing alternatives (languages, platforms) |
| **Accordion** | Collapsible sections |
| **Steps** | Sequential instructions |
| **CodeGroup** | Multi-language code examples |

## Example

Here's a card with an icon that links to another page:

<Card title="Quickstart Guide" icon="rocket" href="/quickstart">
  Get up and running in minutes.
</Card>

```mdx
<Card title="Quickstart Guide" icon="rocket" href="/quickstart">
  Get up and running in minutes.
</Card>
```

<Tip>
Browse the **Components** tab in the sidebar to see live examples of every component.
</Tip>

---

## Pages

*How MDX files become pages, how frontmatter sets titles and descriptions, and how file paths map to URLs in your documentation site.*

Every `.mdx` file in your project becomes a page. The file path determines the URL.

## Frontmatter

Each page starts with frontmatter — metadata between `---` fences:

```mdx
---
title: My Page Title
description: A short description for search engines
---

Your content starts here.
```

| Field | Required | Description |
|-------|----------|-------------|
| `title` | Yes | Page title shown in the browser tab and sidebar |
| `description` | No | Meta description for SEO |

## File organization

Your file structure maps directly to URLs:

```
introduction.mdx        → /introduction
quickstart.mdx          → /quickstart
guides/deployment.mdx   → /guides/deployment
api/users/list.mdx      → /api/users/list
```

## Markdown features

MDX supports all standard Markdown:

- **Bold** and *italic* text
- `Inline code` and fenced code blocks
- [Links](https://example.com) and images
- Ordered and unordered lists
- Tables and blockquotes
- Headings (`##`, `###`, `####`)

<Note>
Headings on the page automatically appear in the right sidebar as a table of contents.
</Note>

---

## Create Plant

---

## Delete Plant

---

## Get Plants

---

## Text Chat Widget

*Embed an AI-powered text chat widget on your website*

## Prerequisites

<Steps>
  <Step title="Get your Workspace ID">
    In the Trillet Portal sidebar, click the **workspace name dropdown** at the top. Your Workspace ID is displayed next to each workspace - click to copy.
  </Step>
  <Step title="Get your Agent ID">
    Navigate to **Call Flows** in the sidebar. Each call flow card displays its **Agent ID** - copy it from the card.
  </Step>
  <Step title="Whitelist your domain">
    Go to **Settings → Domain** and add the domain where you'll embed the widget (e.g. `https://yoursite.com`). This is required to avoid CORS errors. Allow up to 24 hours for propagation. Skip this if you're using a whitelabelled custom domain.
  </Step>
  <Step title="Enable public access">
    Open your call flow, go to the **Settings** tab, and toggle **Public Access** on. Without this, `startPublicCall()` will be rejected.
  </Step>
</Steps>

<Warning>
  Never expose your API key in client-side code. The widget uses `startPublicCall()` which only requires the Workspace ID and Agent ID.
</Warning>

## Integration

Choose between a minimal quick-start snippet or a complete styled widget, then pick your framework.

<Accordion title="Quick Start - Minimal snippet">
  Paste this before the closing `</body>` tag. A chat bubble appears in the bottom-right corner.

  <Tabs>
    <Tab title="HTML / CDN">
```html
<script type="module">
  import { TrilletAgent } from 'https://cdn.jsdelivr.net/npm/@trillet-ai/web-sdk/+esm';

  const WORKSPACE_ID = 'your-workspace-id';
  const AGENT_ID = 'your-agent-id';

  const container = document.createElement('div');
  container.innerHTML = `
    <div id="trillet-chat-bubble" style="position:fixed;bottom:24px;right:24px;width:52px;height:52px;background:#0066ff;border-radius:12px;cursor:pointer;display:flex;align-items:center;justify-content:center;box-shadow:0 1px 3px rgba(0,0,0,0.08);z-index:9999;border:1px solid rgba(0,102,255,0.2);transition:all 0.1s ease-in-out;">
      <svg width="22" height="22" fill="white" viewBox="0 0 24 24"><path d="M20 2H4c-1.1 0-2 .9-2 2v18l4-4h14c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2zm0 14H6l-2 2V4h16v12z"/></svg>
    </div>
  `;
  document.body.appendChild(container);

  const bubble = document.getElementById('trillet-chat-bubble');
  let chatWindow = null;
  let agent = null;
  let isConnected = false;

  bubble.addEventListener('click', () => {
    if (chatWindow) {
      chatWindow.style.display = chatWindow.style.display === 'none' ? 'flex' : 'none';
      return;
    }
    openChat();
  });

  function openChat() {
    chatWindow = document.createElement('div');
    chatWindow.style.cssText = 'position:fixed;bottom:88px;right:24px;width:380px;height:520px;background:#fff;border-radius:12px;border:1px solid #e5e7eb;box-shadow:0 4px 12px -1px rgba(0,0,0,0.05);display:flex;flex-direction:column;overflow:hidden;z-index:9999;font-family:-apple-system,BlinkMacSystemFont,system-ui,sans-serif;';
    chatWindow.innerHTML = `
      <div style="background:#fff;border-bottom:1px solid #e5e7eb;padding:14px 16px;display:flex;justify-content:space-between;align-items:center;">
        <div><div style="font-weight:600;font-size:14px;color:#111827;">Assistant</div><div id="trillet-status" style="font-size:12px;color:#6b7280;">Connecting...</div></div>
        <button id="trillet-close" style="background:none;border:none;color:#9ca3af;cursor:pointer;font-size:16px;padding:4px;">&#x2715;</button>
      </div>
      <div id="trillet-messages" style="flex:1;overflow-y:auto;padding:16px;display:flex;flex-direction:column;gap:8px;background:#f9fafb;"></div>
      <div style="padding:12px;border-top:1px solid #e5e7eb;display:flex;gap:8px;">
        <input id="trillet-input" type="text" placeholder="Type a message..." disabled style="flex:1;padding:9px 14px;border:1px solid #e5e7eb;border-radius:8px;font-size:13px;outline:none;color:#111827;background:#fff;transition:border-color 0.2s;">
        <button id="trillet-send" disabled style="padding:9px 14px;border:none;border-radius:8px;background:#0066ff;color:#fff;font-size:13px;font-weight:500;cursor:pointer;transition:background 0.1s;">Send</button>
      </div>
    `;
    document.body.appendChild(chatWindow);

    document.getElementById('trillet-close').onclick = () => chatWindow.style.display = 'none';
    document.getElementById('trillet-input').onkeypress = (e) => { if (e.key === 'Enter') sendMessage(); };
    document.getElementById('trillet-send').onclick = sendMessage;

    connectAgent();
  }

  async function connectAgent() {
    try {
      agent = new TrilletAgent({ workspaceId: WORKSPACE_ID, agentId: AGENT_ID, mode: 'text' });

      agent.on('connected', () => {
        isConnected = true;
        document.getElementById('trillet-status').textContent = 'Online';
        document.getElementById('trillet-status').style.color = '#10b981';
        document.getElementById('trillet-input').disabled = false;
        document.getElementById('trillet-send').disabled = false;
        document.getElementById('trillet-input').focus();
      });

      agent.on('disconnected', () => {
        isConnected = false;
        document.getElementById('trillet-status').textContent = 'Offline';
        document.getElementById('trillet-status').style.color = '#6b7280';
        document.getElementById('trillet-input').disabled = true;
        document.getElementById('trillet-send').disabled = true;
      });

      agent.on('error', () => addMsg('Something went wrong. Please try again.', 'system'));

      ['message', 'transcript', 'transcriptUpdate'].forEach(evt => {
        agent.on(evt, (data) => {
          let text = typeof data === 'string' ? data : data?.text || data?.content || data?.message;
          if (data?.role && data.role !== 'assistant') return;
          if (data?.isFinal === false) return;
          if (text) addMsg(text, 'assistant');
        });
      });

      await agent.startPublicCall();
    } catch (err) {
      document.getElementById('trillet-status').textContent = 'Failed to connect';
      addMsg('Could not connect. Please refresh and try again.', 'system');
    }
  }

  function sendMessage() {
    const input = document.getElementById('trillet-input');
    const text = input.value.trim();
    if (!text || !isConnected) return;
    addMsg(text, 'user');
    input.value = '';
    try {
      agent.sendTextMessage?.(text) || agent.sendText?.(text) || agent.sendMessage?.(text);
    } catch (e) {
      addMsg('Failed to send message.', 'system');
    }
  }

  const displayed = new Set();
  function addMsg(text, type) {
    const key = type + ':' + text;
    if (displayed.has(key)) return;
    displayed.add(key);
    const el = document.createElement('div');
    const isUser = type === 'user';
    el.style.cssText = `max-width:80%;padding:9px 13px;border-radius:10px;font-size:13px;line-height:1.5;${
      isUser ? 'background:#0066ff;color:#fff;align-self:flex-end;'
      : type === 'system' ? 'background:#f3f4f6;color:#6b7280;align-self:center;font-size:12px;padding:6px 12px;'
      : 'background:#fff;color:#111827;align-self:flex-start;border:1px solid #e5e7eb;'
    }`;
    el.textContent = text;
    const container = document.getElementById('trillet-messages');
    container.appendChild(el);
    container.scrollTop = container.scrollHeight;
  }
</script>
```
    </Tab>
    <Tab title="React / Next.js">
```bash
npm install @trillet-ai/web-sdk
```

```tsx
import { useRef, useState, useEffect } from 'react';
import { TrilletAgent } from '@trillet-ai/web-sdk';

export default function TrilletChat({ workspaceId, agentId }) {
  const agentRef = useRef(null);
  const [isOpen, setIsOpen] = useState(false);
  const [messages, setMessages] = useState([]);
  const [input, setInput] = useState('');
  const [connected, setConnected] = useState(false);

  useEffect(() => {
    if (!isOpen || agentRef.current) return;

    const agent = new TrilletAgent({ workspaceId, agentId, mode: 'text' });
    agentRef.current = agent;

    agent.on('connected', () => setConnected(true));
    agent.on('disconnected', () => setConnected(false));

    ['message', 'transcript'].forEach(evt => {
      agent.on(evt, (data) => {
        const text = typeof data === 'string' ? data : data?.text || data?.content;
        if (data?.role && data.role !== 'assistant') return;
        if (text) setMessages(m => [...m, { type: 'assistant', text }]);
      });
    });

    agent.startPublicCall();
    return () => agent.endCall?.();
  }, [isOpen]);

  const send = () => {
    if (!input.trim() || !connected) return;
    setMessages(m => [...m, { type: 'user', text: input }]);
    agentRef.current?.sendTextMessage?.(input);
    setInput('');
  };

  return (
    <>
      <button onClick={() => setIsOpen(!isOpen)}
        style={{ position: 'fixed', bottom: 24, right: 24, width: 52, height: 52,
          borderRadius: 12, background: '#0066ff', border: '1px solid rgba(0,102,255,0.2)',
          cursor: 'pointer', color: 'white', fontSize: 20, zIndex: 9999,
          boxShadow: '0 1px 3px rgba(0,0,0,0.08)' }}>
        {isOpen ? '✕' : '💬'}
      </button>
      {isOpen && (
        <div style={{ position: 'fixed', bottom: 88, right: 24, width: 380, height: 520,
          background: '#fff', borderRadius: 12, border: '1px solid #e5e7eb',
          boxShadow: '0 4px 12px -1px rgba(0,0,0,0.05)',
          display: 'flex', flexDirection: 'column', zIndex: 9999,
          fontFamily: '-apple-system, BlinkMacSystemFont, system-ui, sans-serif' }}>
          <div style={{ padding: '14px 16px', borderBottom: '1px solid #e5e7eb' }}>
            <div style={{ fontWeight: 600, fontSize: 14, color: '#111827' }}>Assistant</div>
            <div style={{ fontSize: 12, color: connected ? '#10b981' : '#6b7280' }}>
              {connected ? 'Online' : 'Connecting...'}
            </div>
          </div>
          <div style={{ flex: 1, overflowY: 'auto', padding: 16, display: 'flex',
            flexDirection: 'column', gap: 8, background: '#f9fafb' }}>
            {messages.map((m, i) => (
              <div key={i} style={{ alignSelf: m.type === 'user' ? 'flex-end' : 'flex-start',
                background: m.type === 'user' ? '#0066ff' : '#fff',
                color: m.type === 'user' ? '#fff' : '#111827',
                border: m.type === 'user' ? 'none' : '1px solid #e5e7eb',
                padding: '9px 13px', borderRadius: 10, maxWidth: '80%', fontSize: 13 }}>
                {m.text}
              </div>
            ))}
          </div>
          <div style={{ padding: 12, borderTop: '1px solid #e5e7eb', display: 'flex', gap: 8 }}>
            <input value={input} onChange={e => setInput(e.target.value)}
              onKeyDown={e => e.key === 'Enter' && send()}
              placeholder="Type a message..." disabled={!connected}
              style={{ flex: 1, padding: '9px 14px', borderRadius: 8,
                border: '1px solid #e5e7eb', outline: 'none', fontSize: 13 }} />
            <button onClick={send} disabled={!connected}
              style={{ padding: '9px 14px', borderRadius: 8, background: '#0066ff',
                color: '#fff', border: 'none', cursor: 'pointer', fontSize: 13, fontWeight: 500 }}>
              Send
            </button>
          </div>
        </div>
      )}
    </>
  );
}
```

Usage:
```tsx
<TrilletChat workspaceId="your-workspace-id" agentId="your-agent-id" />
```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="Full Widget - Complete styled chat widget">
  A polished chat widget with status indicators, typing animation, and transcript polling. Self-contained HTML file you can use directly or hand off.

  <Tabs>
    <Tab title="HTML / CDN">
```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Trillet Chat Widget</title>
  <style>
    * { box-sizing: border-box; }

    #trillet-bubble {
      position: fixed;
      bottom: 24px;
      right: 24px;
      width: 52px;
      height: 52px;
      background: #0066ff;
      border-radius: 12px;
      cursor: pointer;
      display: flex;
      align-items: center;
      justify-content: center;
      box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
      border: 1px solid rgba(0, 102, 255, 0.2);
      z-index: 9999;
      transition: all 0.1s ease-in-out;
    }
    #trillet-bubble:hover { background: #0052cc; }
    #trillet-bubble svg { width: 22px; height: 22px; fill: white; }

    #trillet-panel {
      position: fixed;
      bottom: 88px;
      right: 24px;
      width: 380px;
      height: 540px;
      background: #fff;
      border-radius: 12px;
      border: 1px solid #e5e7eb;
      box-shadow: 0 4px 12px -1px rgba(0, 0, 0, 0.05);
      display: none;
      flex-direction: column;
      overflow: hidden;
      z-index: 9999;
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif;
    }
    #trillet-panel.open { display: flex; animation: trillet-in 0.15s cubic-bezier(0.16,1,0.3,1); }

    @keyframes trillet-in {
      from { opacity: 0; transform: translateY(8px); }
      to { opacity: 1; transform: translateY(0); }
    }

    .trillet-header {
      padding: 14px 16px;
      border-bottom: 1px solid #e5e7eb;
      display: flex;
      justify-content: space-between;
      align-items: center;
      background: #fff;
    }
    .trillet-header h3 { font-size: 14px; font-weight: 600; margin: 0; color: #111827; }
    .trillet-header .status {
      font-size: 12px;
      color: #6b7280;
      display: flex;
      align-items: center;
      gap: 5px;
      margin-top: 1px;
    }
    .trillet-header .status-dot {
      width: 6px; height: 6px;
      border-radius: 50%;
      background: #d1d5db;
    }
    .trillet-header .status-dot.online { background: #10b981; }
    .trillet-close {
      background: none;
      border: none;
      color: #9ca3af;
      cursor: pointer;
      font-size: 16px;
      padding: 4px;
      line-height: 1;
      transition: color 0.1s;
    }
    .trillet-close:hover { color: #6b7280; }

    .trillet-messages {
      flex: 1;
      overflow-y: auto;
      padding: 16px;
      display: flex;
      flex-direction: column;
      gap: 8px;
      background: #f9fafb;
    }
    .trillet-msg {
      max-width: 82%;
      padding: 9px 13px;
      border-radius: 10px;
      font-size: 13px;
      line-height: 1.5;
    }
    .trillet-msg.user {
      background: #0066ff;
      color: #fff;
      align-self: flex-end;
    }
    .trillet-msg.assistant {
      background: #fff;
      color: #111827;
      align-self: flex-start;
      border: 1px solid #e5e7eb;
    }
    .trillet-msg.system {
      background: #f3f4f6;
      color: #6b7280;
      align-self: center;
      font-size: 11px;
      padding: 4px 10px;
      border-radius: 6px;
    }

    .trillet-typing {
      display: flex;
      gap: 4px;
      padding: 10px 14px;
      background: #fff;
      border: 1px solid #e5e7eb;
      border-radius: 10px;
      align-self: flex-start;
    }
    .trillet-typing span {
      width: 5px; height: 5px;
      background: #9ca3af;
      border-radius: 50%;
      animation: trillet-dot 1.4s infinite ease-in-out;
    }
    .trillet-typing span:nth-child(2) { animation-delay: 0.2s; }
    .trillet-typing span:nth-child(3) { animation-delay: 0.4s; }
    @keyframes trillet-dot {
      0%, 60%, 100% { transform: translateY(0); opacity: 0.4; }
      30% { transform: translateY(-3px); opacity: 1; }
    }

    .trillet-input-area {
      padding: 12px;
      border-top: 1px solid #e5e7eb;
      display: flex;
      gap: 8px;
      background: #fff;
    }
    .trillet-input-area input {
      flex: 1;
      padding: 9px 14px;
      border: 1px solid #e5e7eb;
      border-radius: 8px;
      font-size: 13px;
      outline: none;
      color: #111827;
      transition: border-color 0.2s;
    }
    .trillet-input-area input:focus { border-color: #0066ff; }
    .trillet-input-area input:disabled { background: #f9fafb; color: #9ca3af; }
    .trillet-send {
      padding: 9px 14px;
      border: none;
      border-radius: 8px;
      background: #0066ff;
      color: #fff;
      cursor: pointer;
      font-size: 13px;
      font-weight: 500;
      transition: background 0.1s;
    }
    .trillet-send:hover:not(:disabled) { background: #0052cc; }
    .trillet-send:disabled { background: #d1d5db; cursor: not-allowed; }

    @media (max-width: 480px) {
      #trillet-panel {
        width: calc(100vw - 24px);
        height: calc(100vh - 140px);
        right: 12px;
        bottom: 88px;
      }
    }
  </style>
</head>
<body>

  <!-- Paste everything below into your website -->
  <button id="trillet-bubble">
    <svg viewBox="0 0 24 24"><path d="M20 2H4c-1.1 0-2 .9-2 2v18l4-4h14c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2zm0 14H6l-2 2V4h16v12z"/></svg>
  </button>

  <div id="trillet-panel">
    <div class="trillet-header">
      <div>
        <h3>Assistant</h3>
        <div class="status">
          <div class="status-dot" id="trillet-dot"></div>
          <span id="trillet-status-text">Ready</span>
        </div>
      </div>
      <button class="trillet-close" id="trillet-close">&#x2715;</button>
    </div>
    <div class="trillet-messages" id="trillet-messages"></div>
    <div class="trillet-input-area">
      <input type="text" id="trillet-input" placeholder="Type a message..." disabled>
      <button class="trillet-send" id="trillet-send" disabled>Send</button>
    </div>
  </div>

  <script type="module">
    import { TrilletAgent } from 'https://cdn.jsdelivr.net/npm/@trillet-ai/web-sdk/+esm';

    // ── REPLACE THESE WITH YOUR VALUES ──
    const WORKSPACE_ID = 'your-workspace-id';
    const AGENT_ID = 'your-agent-id';
    // ─────────────────────────────────────

    const $ = (id) => document.getElementById(id);
    const bubble = $('trillet-bubble');
    const panel = $('trillet-panel');

    let agent = null;
    let isConnected = false;
    let hasConnected = false;
    const displayed = new Set();

    bubble.addEventListener('click', () => {
      panel.classList.toggle('open');
      if (!hasConnected) {
        hasConnected = true;
        connectAgent();
      }
    });

    $('trillet-close').addEventListener('click', () => panel.classList.remove('open'));
    $('trillet-input').addEventListener('keypress', (e) => { if (e.key === 'Enter') sendMessage(); });
    $('trillet-send').addEventListener('click', sendMessage);

    async function connectAgent() {
      setStatus('Connecting...', false);
      try {
        agent = new TrilletAgent({
          workspaceId: WORKSPACE_ID,
          agentId: AGENT_ID,
          mode: 'text',
        });

        agent.on('connected', () => {
          isConnected = true;
          setStatus('Online', true);
          $('trillet-input').disabled = false;
          $('trillet-send').disabled = false;
          $('trillet-input').focus();
          startPolling();
        });

        agent.on('disconnected', () => {
          isConnected = false;
          setStatus('Offline', false);
          $('trillet-input').disabled = true;
          $('trillet-send').disabled = true;
          addMsg('Session ended.', 'system');
        });

        agent.on('error', () => addMsg('Something went wrong. Please try again.', 'system'));

        ['message', 'transcript', 'transcriptUpdate', 'response'].forEach(evt => {
          agent.on(evt, (data) => {
            hideTyping();
            let text = typeof data === 'string' ? data : data?.text || data?.content || data?.message;
            if (data?.role && data.role !== 'assistant') return;
            if (data?.isFinal === false) return;
            if (text) addMsg(text, 'assistant');
          });
        });

        agent.on('assistantStartedSpeaking', showTyping);
        agent.on('assistantStoppedSpeaking', hideTyping);

        await agent.startPublicCall();
      } catch (err) {
        setStatus('Failed', false);
        addMsg('Could not connect. Please refresh and try again.', 'system');
      }
    }

    let pollInterval = null;
    function startPolling() {
      let lastCount = 0;
      pollInterval = setInterval(() => {
        if (!agent || !isConnected) return;
        try {
          const transcripts = agent.getTranscripts?.() || [];
          for (let i = lastCount; i < transcripts.length; i++) {
            const t = transcripts[i];
            if (t.role === 'assistant' && t.text) { hideTyping(); addMsg(t.text, 'assistant'); }
          }
          lastCount = transcripts.length;
        } catch (e) {}
      }, 500);
    }

    function sendMessage() {
      const input = $('trillet-input');
      const text = input.value.trim();
      if (!text || !isConnected) return;
      addMsg(text, 'user');
      input.value = '';
      showTyping();
      try {
        if (agent.sendTextMessage) agent.sendTextMessage(text);
        else if (agent.sendText) agent.sendText(text);
        else if (agent.sendMessage) agent.sendMessage(text);
      } catch (e) {
        hideTyping();
        addMsg('Failed to send message.', 'system');
      }
    }

    function setStatus(text, online) {
      $('trillet-status-text').textContent = text;
      $('trillet-dot').classList.toggle('online', online);
    }

    function addMsg(text, type) {
      if (!text?.trim()) return;
      const key = type + ':' + text;
      if (displayed.has(key)) return;
      displayed.add(key);
      const el = document.createElement('div');
      el.className = 'trillet-msg ' + type;
      el.textContent = text;
      $('trillet-messages').appendChild(el);
      $('trillet-messages').scrollTop = $('trillet-messages').scrollHeight;
    }

    function showTyping() {
      if (document.getElementById('trillet-typing')) return;
      const el = document.createElement('div');
      el.className = 'trillet-typing';
      el.id = 'trillet-typing';
      el.innerHTML = '<span></span><span></span><span></span>';
      $('trillet-messages').appendChild(el);
      $('trillet-messages').scrollTop = $('trillet-messages').scrollHeight;
    }

    function hideTyping() {
      document.getElementById('trillet-typing')?.remove();
    }
  </script>

</body>
</html>
```
    </Tab>
    <Tab title="React / Next.js">
```bash
npm install @trillet-ai/web-sdk
```

```tsx
import { useRef, useState, useEffect, useCallback } from 'react';
import { TrilletAgent } from '@trillet-ai/web-sdk';

export default function TrilletChat({ workspaceId, agentId }) {
  const agentRef = useRef(null);
  const messagesRef = useRef(null);
  const [isOpen, setIsOpen] = useState(false);
  const [messages, setMessages] = useState([]);
  const [input, setInput] = useState('');
  const [connected, setConnected] = useState(false);

  useEffect(() => {
    if (!isOpen || agentRef.current) return;

    const agent = new TrilletAgent({ workspaceId, agentId, mode: 'text' });
    agentRef.current = agent;

    agent.on('connected', () => setConnected(true));
    agent.on('disconnected', () => setConnected(false));

    ['message', 'transcript'].forEach(evt => {
      agent.on(evt, (data) => {
        const text = typeof data === 'string' ? data : data?.text || data?.content;
        if (data?.role && data.role !== 'assistant') return;
        if (text) setMessages(m => [...m, { type: 'assistant', text }]);
      });
    });

    agent.startPublicCall();

    // Poll transcripts as fallback
    let lastCount = 0;
    const poll = setInterval(() => {
      const transcripts = agent.getTranscripts?.() || [];
      for (let i = lastCount; i < transcripts.length; i++) {
        const t = transcripts[i];
        if (t.role === 'assistant' && t.text) {
          setMessages(m => [...m, { type: 'assistant', text: t.text }]);
        }
      }
      lastCount = transcripts.length;
    }, 500);

    return () => { clearInterval(poll); agent.endCall?.(); };
  }, [isOpen]);

  useEffect(() => {
    messagesRef.current?.scrollTo(0, messagesRef.current.scrollHeight);
  }, [messages]);

  const send = useCallback(() => {
    if (!input.trim() || !connected) return;
    setMessages(m => [...m, { type: 'user', text: input }]);
    agentRef.current?.sendTextMessage?.(input);
    setInput('');
  }, [input, connected]);

  const styles = {
    bubble: { position: 'fixed', bottom: 24, right: 24, width: 52, height: 52,
      borderRadius: 12, background: '#0066ff', border: '1px solid rgba(0,102,255,0.2)',
      cursor: 'pointer', color: '#fff', display: 'flex', alignItems: 'center',
      justifyContent: 'center', zIndex: 9999, boxShadow: '0 1px 3px rgba(0,0,0,0.08)' },
    panel: { position: 'fixed', bottom: 88, right: 24, width: 380, height: 540,
      background: '#fff', borderRadius: 12, border: '1px solid #e5e7eb',
      boxShadow: '0 4px 12px -1px rgba(0,0,0,0.05)',
      display: 'flex', flexDirection: 'column', zIndex: 9999,
      fontFamily: '-apple-system, BlinkMacSystemFont, system-ui, sans-serif' },
    header: { padding: '14px 16px', borderBottom: '1px solid #e5e7eb',
      display: 'flex', justifyContent: 'space-between', alignItems: 'center' },
    msgUser: { alignSelf: 'flex-end', background: '#0066ff', color: '#fff',
      padding: '9px 13px', borderRadius: 10, maxWidth: '80%', fontSize: 13 },
    msgBot: { alignSelf: 'flex-start', background: '#fff', color: '#111827',
      border: '1px solid #e5e7eb', padding: '9px 13px', borderRadius: 10,
      maxWidth: '80%', fontSize: 13 },
  };

  return (
    <>
      <button onClick={() => setIsOpen(!isOpen)} style={styles.bubble}>
        {isOpen
          ? <svg width="18" height="18" fill="none" stroke="#fff" strokeWidth="2" viewBox="0 0 24 24"><path d="M18 6L6 18M6 6l12 12"/></svg>
          : <svg width="22" height="22" fill="#fff" viewBox="0 0 24 24"><path d="M20 2H4c-1.1 0-2 .9-2 2v18l4-4h14c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2zm0 14H6l-2 2V4h16v12z"/></svg>}
      </button>
      {isOpen && (
        <div style={styles.panel}>
          <div style={styles.header}>
            <div>
              <div style={{ fontWeight: 600, fontSize: 14, color: '#111827' }}>Assistant</div>
              <div style={{ fontSize: 12, color: connected ? '#10b981' : '#6b7280' }}>
                {connected ? 'Online' : 'Connecting...'}
              </div>
            </div>
            <button onClick={() => setIsOpen(false)}
              style={{ background: 'none', border: 'none', color: '#9ca3af', cursor: 'pointer', fontSize: 16 }}>
              &#x2715;
            </button>
          </div>
          <div ref={messagesRef} style={{ flex: 1, overflowY: 'auto', padding: 16,
            display: 'flex', flexDirection: 'column', gap: 8, background: '#f9fafb' }}>
            {messages.map((m, i) => (
              <div key={i} style={m.type === 'user' ? styles.msgUser : styles.msgBot}>
                {m.text}
              </div>
            ))}
          </div>
          <div style={{ padding: 12, borderTop: '1px solid #e5e7eb', display: 'flex', gap: 8 }}>
            <input value={input} onChange={e => setInput(e.target.value)}
              onKeyDown={e => e.key === 'Enter' && send()}
              placeholder="Type a message..." disabled={!connected}
              style={{ flex: 1, padding: '9px 14px', borderRadius: 8,
                border: '1px solid #e5e7eb', outline: 'none', fontSize: 13 }} />
            <button onClick={send} disabled={!connected}
              style={{ padding: '9px 14px', borderRadius: 8, background: '#0066ff',
                color: '#fff', border: 'none', cursor: 'pointer', fontSize: 13, fontWeight: 500 }}>
              Send
            </button>
          </div>
        </div>
      )}
    </>
  );
}
```

Usage:
```tsx
<TrilletChat workspaceId="your-workspace-id" agentId="your-agent-id" />
```
    </Tab>
  </Tabs>
</Accordion>

## Events Reference

The SDK emits these events you can listen to:

| Event | Description |
|---|---|
| `connected` | Agent is connected and ready |
| `disconnected` | Session ended |
| `error` | An error occurred |
| `message` | New message received |
| `transcript` | Transcript update received |
| `assistantStartedSpeaking` | Agent begins responding |
| `assistantStoppedSpeaking` | Agent finished responding |

```js
agent.on('connected', (details) => {
  console.log('Connected:', details.callId);
});
```

---

## Voice Agent Widget

*Embed an AI-powered voice agent on your website*

## Prerequisites

<Steps>
  <Step title="Get your Workspace ID">
    In the Trillet Portal sidebar, click the **workspace name dropdown** at the top. Your Workspace ID is displayed next to each workspace - click to copy.
  </Step>
  <Step title="Get your Agent ID">
    Navigate to **Call Flows** in the sidebar. Each call flow card displays its **Agent ID** - copy it from the card.
  </Step>
  <Step title="Whitelist your domain">
    Go to **Settings → Domain** and add the domain where you'll embed the widget (e.g. `https://yoursite.com`). This is required to avoid CORS errors. Allow up to 24 hours for propagation. Skip this if you're using a whitelabelled custom domain.
  </Step>
  <Step title="Enable public access">
    Open your call flow, go to the **Settings** tab, and toggle **Public Access** on. Without this, `startPublicCall()` will be rejected.
  </Step>
</Steps>

<Warning>
  The voice widget requires **microphone permissions** and must be served over **HTTPS** (or localhost). Browsers block microphone access on insecure origins.
</Warning>

## Integration

Choose between a minimal quick-start snippet or a complete styled widget, then pick your framework.

<Accordion title="Quick Start - Minimal snippet">
  Paste this before the closing `</body>` tag. A mic button appears in the bottom-right corner.

  <Tabs>
    <Tab title="HTML / CDN">
```html
<script type="module">
  import { TrilletAgent } from 'https://cdn.jsdelivr.net/npm/@trillet-ai/web-sdk/+esm';

  const WORKSPACE_ID = 'your-workspace-id';
  const AGENT_ID = 'your-agent-id';

  const btn = document.createElement('button');
  btn.id = 'trillet-voice-btn';
  btn.innerHTML = `<svg width="22" height="22" fill="white" viewBox="0 0 24 24"><path d="M12 14c1.66 0 3-1.34 3-3V5c0-1.66-1.34-3-3-3S9 3.34 9 5v6c0 1.66 1.34 3 3 3zm-1-9c0-.55.45-1 1-1s1 .45 1 1v6c0 .55-.45 1-1 1s-1-.45-1-1V5zm6 6c0 2.76-2.24 5-5 5s-5-2.24-5-5H5c0 3.53 2.61 6.43 6 6.92V21h2v-3.08c3.39-.49 6-3.39 6-6.92h-2z"/></svg>`;
  btn.style.cssText = 'position:fixed;bottom:24px;right:24px;width:52px;height:52px;border-radius:12px;background:#0066ff;border:1px solid rgba(0,102,255,0.2);cursor:pointer;display:flex;align-items:center;justify-content:center;box-shadow:0 1px 3px rgba(0,0,0,0.08);z-index:9999;transition:all 0.1s ease-in-out;';
  document.body.appendChild(btn);

  let agent = null;
  let isActive = false;

  btn.addEventListener('click', async () => {
    if (isActive) { agent?.endCall(); return; }

    btn.style.background = '#d1d5db';
    btn.disabled = true;

    try {
      agent = new TrilletAgent({ workspaceId: WORKSPACE_ID, agentId: AGENT_ID, mode: 'voice' });

      agent.on('connected', () => {
        isActive = true;
        btn.disabled = false;
        btn.style.background = '#ef4444';
        btn.style.borderColor = 'rgba(239,68,68,0.2)';
        btn.innerHTML = `<svg width="20" height="20" fill="white" viewBox="0 0 24 24"><path d="M12 9c-1.6 0-3.15.25-4.6.72v3.1c0 .39-.23.74-.56.9-.98.49-1.87 1.12-2.66 1.85-.18.18-.43.28-.7.28-.28 0-.53-.11-.71-.29L.29 13.08a.956.956 0 010-1.36C3.55 8.67 7.56 7 12 7s8.45 1.67 11.71 4.72c.18.18.29.43.29.71 0 .28-.11.53-.29.71l-2.48 2.48c-.18.18-.43.29-.71.29-.27 0-.52-.1-.7-.28-.79-.73-1.68-1.36-2.66-1.85a.993.993 0 01-.56-.9v-3.1C15.15 9.25 13.6 9 12 9z"/></svg>`;
      });

      agent.on('disconnected', () => {
        isActive = false;
        btn.style.background = '#0066ff';
        btn.style.borderColor = 'rgba(0,102,255,0.2)';
        btn.innerHTML = `<svg width="22" height="22" fill="white" viewBox="0 0 24 24"><path d="M12 14c1.66 0 3-1.34 3-3V5c0-1.66-1.34-3-3-3S9 3.34 9 5v6c0 1.66 1.34 3 3 3zm-1-9c0-.55.45-1 1-1s1 .45 1 1v6c0 .55-.45 1-1 1s-1-.45-1-1V5zm6 6c0 2.76-2.24 5-5 5s-5-2.24-5-5H5c0 3.53 2.61 6.43 6 6.92V21h2v-3.08c3.39-.49 6-3.39 6-6.92h-2z"/></svg>`;
        btn.disabled = false;
      });

      agent.on('error', () => {
        btn.style.background = '#0066ff';
        btn.style.borderColor = 'rgba(0,102,255,0.2)';
        btn.innerHTML = `<svg width="22" height="22" fill="white" viewBox="0 0 24 24"><path d="M12 14c1.66 0 3-1.34 3-3V5c0-1.66-1.34-3-3-3S9 3.34 9 5v6c0 1.66 1.34 3 3 3zm-1-9c0-.55.45-1 1-1s1 .45 1 1v6c0 .55-.45 1-1 1s-1-.45-1-1V5zm6 6c0 2.76-2.24 5-5 5s-5-2.24-5-5H5c0 3.53 2.61 6.43 6 6.92V21h2v-3.08c3.39-.49 6-3.39 6-6.92h-2z"/></svg>`;
        btn.disabled = false;
        isActive = false;
      });

      await agent.startPublicCall();
    } catch (err) {
      btn.style.background = '#0066ff';
      btn.style.borderColor = 'rgba(0,102,255,0.2)';
      btn.innerHTML = `<svg width="22" height="22" fill="white" viewBox="0 0 24 24"><path d="M12 14c1.66 0 3-1.34 3-3V5c0-1.66-1.34-3-3-3S9 3.34 9 5v6c0 1.66 1.34 3 3 3zm-1-9c0-.55.45-1 1-1s1 .45 1 1v6c0 .55-.45 1-1 1s-1-.45-1-1V5zm6 6c0 2.76-2.24 5-5 5s-5-2.24-5-5H5c0 3.53 2.61 6.43 6 6.92V21h2v-3.08c3.39-.49 6-3.39 6-6.92h-2z"/></svg>`;
      btn.disabled = false;
    }
  });
</script>
```
    </Tab>
    <Tab title="React / Next.js">
```bash
npm install @trillet-ai/web-sdk
```

```tsx
import { useRef, useState, useEffect } from 'react';
import { TrilletAgent } from '@trillet-ai/web-sdk';

export default function TrilletVoice({ workspaceId, agentId }) {
  const agentRef = useRef(null);
  const [isActive, setIsActive] = useState(false);
  const [status, setStatus] = useState('idle');

  const startCall = async () => {
    const agent = new TrilletAgent({ workspaceId, agentId, mode: 'voice' });
    agentRef.current = agent;
    setStatus('connecting');

    agent.on('connected', () => { setIsActive(true); setStatus('connected'); });
    agent.on('disconnected', () => { setIsActive(false); setStatus('idle'); });
    agent.on('error', () => setStatus('error'));

    try {
      await agent.startPublicCall();
    } catch {
      setStatus('error');
    }
  };

  const endCall = () => agentRef.current?.endCall();
  useEffect(() => () => agentRef.current?.endCall?.(), []);

  return (
    <button onClick={isActive ? endCall : startCall} disabled={status === 'connecting'}
      style={{ position: 'fixed', bottom: 24, right: 24, width: 52, height: 52,
        borderRadius: 12, background: isActive ? '#ef4444' : '#0066ff',
        border: `1px solid ${isActive ? 'rgba(239,68,68,0.2)' : 'rgba(0,102,255,0.2)'}`,
        cursor: 'pointer', color: '#fff', display: 'flex', alignItems: 'center',
        justifyContent: 'center', zIndex: 9999, boxShadow: '0 1px 3px rgba(0,0,0,0.08)' }}>
      {status === 'connecting' ? '...' : isActive ? '📞' : '🎙️'}
    </button>
  );
}
```

Usage:
```tsx
<TrilletVoice workspaceId="your-workspace-id" agentId="your-agent-id" />
```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="Full Widget - Voice panel with controls and transcript">
  A polished voice widget with mute/unmute, end call, audio visualizer, and live transcript display.

  <Tabs>
    <Tab title="HTML / CDN">
```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Trillet Voice Widget</title>
  <style>
    * { box-sizing: border-box; }

    #trillet-v-bubble {
      position: fixed;
      bottom: 24px;
      right: 24px;
      width: 52px;
      height: 52px;
      background: #0066ff;
      border-radius: 12px;
      cursor: pointer;
      display: flex;
      align-items: center;
      justify-content: center;
      box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
      border: 1px solid rgba(0, 102, 255, 0.2);
      z-index: 9999;
      transition: all 0.1s ease-in-out;
    }
    #trillet-v-bubble:hover { background: #0052cc; }
    #trillet-v-bubble svg { width: 22px; height: 22px; fill: white; }

    #trillet-v-panel {
      position: fixed;
      bottom: 88px;
      right: 24px;
      width: 340px;
      background: #fff;
      border-radius: 12px;
      border: 1px solid #e5e7eb;
      box-shadow: 0 4px 12px -1px rgba(0, 0, 0, 0.05);
      display: none;
      flex-direction: column;
      overflow: hidden;
      z-index: 9999;
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif;
    }
    #trillet-v-panel.open { display: flex; animation: trillet-v-in 0.15s cubic-bezier(0.16,1,0.3,1); }

    @keyframes trillet-v-in {
      from { opacity: 0; transform: translateY(8px); }
      to { opacity: 1; transform: translateY(0); }
    }

    .trillet-v-header {
      padding: 14px 16px;
      border-bottom: 1px solid #e5e7eb;
      display: flex;
      justify-content: space-between;
      align-items: center;
    }
    .trillet-v-header h3 { font-size: 14px; font-weight: 600; margin: 0; color: #111827; }
    .trillet-v-header .status {
      font-size: 12px; color: #6b7280;
      display: flex; align-items: center; gap: 5px; margin-top: 1px;
    }
    .trillet-v-header .status-dot {
      width: 6px; height: 6px; border-radius: 50%; background: #d1d5db;
    }
    .trillet-v-header .status-dot.online { background: #10b981; }
    .trillet-v-close {
      background: none; border: none; color: #9ca3af;
      cursor: pointer; font-size: 16px; padding: 4px; line-height: 1;
      transition: color 0.1s;
    }
    .trillet-v-close:hover { color: #6b7280; }

    .trillet-v-transcript {
      max-height: 180px;
      overflow-y: auto;
      padding: 12px 16px;
      display: flex;
      flex-direction: column;
      gap: 6px;
      background: #f9fafb;
    }
    .trillet-v-msg {
      max-width: 85%;
      padding: 7px 11px;
      border-radius: 8px;
      font-size: 12px;
      line-height: 1.4;
    }
    .trillet-v-msg.user {
      background: #0066ff; color: #fff; align-self: flex-end;
    }
    .trillet-v-msg.assistant {
      background: #fff; color: #111827; align-self: flex-start;
      border: 1px solid #e5e7eb;
    }
    .trillet-v-msg.system {
      background: #f3f4f6; color: #6b7280;
      align-self: center; font-size: 11px; padding: 3px 8px; border-radius: 4px;
    }

    .trillet-v-controls {
      padding: 20px;
      background: #fff;
      border-top: 1px solid #e5e7eb;
      display: flex;
      flex-direction: column;
      align-items: center;
      gap: 14px;
    }

    .trillet-v-vis {
      display: flex; align-items: center; justify-content: center;
      gap: 3px; height: 32px;
    }
    .trillet-v-vis .bar {
      width: 3px; height: 6px;
      background: #0066ff; border-radius: 2px;
      transition: height 0.1s;
    }
    .trillet-v-vis.active .bar {
      animation: trillet-pulse 0.8s infinite ease-in-out;
    }
    .trillet-v-vis.active .bar:nth-child(1) { animation-delay: 0s; }
    .trillet-v-vis.active .bar:nth-child(2) { animation-delay: 0.1s; }
    .trillet-v-vis.active .bar:nth-child(3) { animation-delay: 0.2s; }
    .trillet-v-vis.active .bar:nth-child(4) { animation-delay: 0.3s; }
    .trillet-v-vis.active .bar:nth-child(5) { animation-delay: 0.4s; }
    .trillet-v-vis.active .bar:nth-child(6) { animation-delay: 0.3s; }
    .trillet-v-vis.active .bar:nth-child(7) { animation-delay: 0.2s; }
    @keyframes trillet-pulse {
      0%, 100% { height: 6px; }
      50% { height: 22px; }
    }

    .trillet-v-label {
      font-size: 12px; color: #6b7280; font-weight: 500;
    }

    .trillet-v-btns {
      display: flex; align-items: center; gap: 12px;
    }
    .trillet-v-mic {
      width: 48px; height: 48px; border-radius: 12px; border: none;
      cursor: pointer; display: flex; align-items: center; justify-content: center;
      transition: all 0.1s;
    }
    .trillet-v-mic.idle {
      background: #0066ff; color: white;
      border: 1px solid rgba(0, 102, 255, 0.2);
      box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
    }
    .trillet-v-mic.idle:hover { background: #0052cc; }
    .trillet-v-mic.active {
      background: #0066ff; color: white;
      border: 1px solid rgba(0, 102, 255, 0.2);
    }
    .trillet-v-mic.muted {
      background: #fef2f2; color: #ef4444;
      border: 1px solid rgba(239, 68, 68, 0.15);
    }
    .trillet-v-mic svg { width: 20px; height: 20px; }

    .trillet-v-end {
      width: 40px; height: 40px; border-radius: 12px; border: none;
      background: #ef4444; color: white; cursor: pointer;
      border: 1px solid rgba(239, 68, 68, 0.2);
      display: flex; align-items: center; justify-content: center;
      transition: background 0.1s;
    }
    .trillet-v-end:hover { background: #dc2626; }
    .trillet-v-end svg { width: 18px; height: 18px; }

    @media (max-width: 480px) {
      #trillet-v-panel {
        width: calc(100vw - 24px);
        right: 12px;
        bottom: 88px;
      }
    }
  </style>
</head>
<body>

  <!-- Paste everything below into your website -->
  <button id="trillet-v-bubble">
    <svg viewBox="0 0 24 24"><path d="M12 14c1.66 0 3-1.34 3-3V5c0-1.66-1.34-3-3-3S9 3.34 9 5v6c0 1.66 1.34 3 3 3zm-1-9c0-.55.45-1 1-1s1 .45 1 1v6c0 .55-.45 1-1 1s-1-.45-1-1V5zm6 6c0 2.76-2.24 5-5 5s-5-2.24-5-5H5c0 3.53 2.61 6.43 6 6.92V21h2v-3.08c3.39-.49 6-3.39 6-6.92h-2z"/></svg>
  </button>

  <div id="trillet-v-panel">
    <div class="trillet-v-header">
      <div>
        <h3>Voice Assistant</h3>
        <div class="status">
          <div class="status-dot" id="trillet-v-dot"></div>
          <span id="trillet-v-status-text">Ready</span>
        </div>
      </div>
      <button class="trillet-v-close" id="trillet-v-close">&#x2715;</button>
    </div>
    <div class="trillet-v-transcript" id="trillet-v-transcript"></div>
    <div class="trillet-v-controls">
      <div class="trillet-v-vis" id="trillet-v-vis">
        <div class="bar"></div><div class="bar"></div><div class="bar"></div>
        <div class="bar"></div>
        <div class="bar"></div><div class="bar"></div><div class="bar"></div>
      </div>
      <div class="trillet-v-label" id="trillet-v-label">Tap the mic to start</div>
      <div class="trillet-v-btns" id="trillet-v-btns">
        <button class="trillet-v-mic idle" id="trillet-v-mic">
          <svg viewBox="0 0 24 24" fill="currentColor"><path d="M12 14c1.66 0 3-1.34 3-3V5c0-1.66-1.34-3-3-3S9 3.34 9 5v6c0 1.66 1.34 3 3 3zm-1-9c0-.55.45-1 1-1s1 .45 1 1v6c0 .55-.45 1-1 1s-1-.45-1-1V5zm6 6c0 2.76-2.24 5-5 5s-5-2.24-5-5H5c0 3.53 2.61 6.43 6 6.92V21h2v-3.08c3.39-.49 6-3.39 6-6.92h-2z"/></svg>
        </button>
      </div>
    </div>
  </div>

  <script type="module">
    import { TrilletAgent } from 'https://cdn.jsdelivr.net/npm/@trillet-ai/web-sdk/+esm';

    // ── REPLACE THESE WITH YOUR VALUES ──
    const WORKSPACE_ID = 'your-workspace-id';
    const AGENT_ID = 'your-agent-id';
    // ─────────────────────────────────────

    const $ = (id) => document.getElementById(id);
    const bubble = $('trillet-v-bubble');
    const panel = $('trillet-v-panel');
    const micSvg = `<svg viewBox="0 0 24 24" fill="currentColor"><path d="M12 14c1.66 0 3-1.34 3-3V5c0-1.66-1.34-3-3-3S9 3.34 9 5v6c0 1.66 1.34 3 3 3zm-1-9c0-.55.45-1 1-1s1 .45 1 1v6c0 .55-.45 1-1 1s-1-.45-1-1V5zm6 6c0 2.76-2.24 5-5 5s-5-2.24-5-5H5c0 3.53 2.61 6.43 6 6.92V21h2v-3.08c3.39-.49 6-3.39 6-6.92h-2z"/></svg>`;
    const micMutedSvg = `<svg viewBox="0 0 24 24" fill="currentColor"><path d="M19 11h-1.7c0 .74-.16 1.43-.43 2.05l1.23 1.23c.56-.98.9-2.09.9-3.28zm-4.02.17c0-.06.02-.11.02-.17V5c0-1.66-1.34-3-3-3S9 3.34 9 5v.18l5.98 5.99zM4.27 3L3 4.27l6.01 6.01V11c0 1.66 1.33 3 2.99 3 .22 0 .44-.03.65-.08l1.66 1.66c-.71.33-1.5.52-2.31.52-2.76 0-5.3-2.1-5.3-5.1H5c0 3.41 2.72 6.23 6 6.72V21h2v-3.28c.91-.13 1.77-.45 2.54-.9L19.73 21 21 19.73 4.27 3z"/></svg>`;
    const hangupSvg = `<svg viewBox="0 0 24 24" fill="currentColor"><path d="M12 9c-1.6 0-3.15.25-4.6.72v3.1c0 .39-.23.74-.56.9-.98.49-1.87 1.12-2.66 1.85-.18.18-.43.28-.7.28-.28 0-.53-.11-.71-.29L.29 13.08a.956.956 0 010-1.36C3.55 8.67 7.56 7 12 7s8.45 1.67 11.71 4.72c.18.18.29.43.29.71 0 .28-.11.53-.29.71l-2.48 2.48c-.18.18-.43.29-.71.29-.27 0-.52-.1-.7-.28-.79-.73-1.68-1.36-2.66-1.85a.993.993 0 01-.56-.9v-3.1C15.15 9.25 13.6 9 12 9z"/></svg>`;

    let agent = null;
    let isActive = false;
    let isMuted = false;
    let pollInterval = null;
    const displayed = new Set();

    bubble.addEventListener('click', () => panel.classList.toggle('open'));
    $('trillet-v-close').addEventListener('click', () => panel.classList.remove('open'));

    $('trillet-v-mic').addEventListener('click', () => {
      if (!isActive) connectAgent();
      else toggleMute();
    });

    async function connectAgent() {
      setStatus('Connecting...', false);
      $('trillet-v-label').textContent = 'Connecting...';
      $('trillet-v-mic').disabled = true;

      try {
        agent = new TrilletAgent({
          workspaceId: WORKSPACE_ID,
          agentId: AGENT_ID,
          mode: 'voice',
        });

        agent.on('connected', () => {
          isActive = true;
          isMuted = false;
          setStatus('Connected', true);
          $('trillet-v-label').textContent = 'Listening...';
          $('trillet-v-vis').classList.add('active');
          $('trillet-v-mic').disabled = false;
          showActiveControls();
          addMsg('Voice call connected', 'system');
          startPolling();
        });

        agent.on('disconnected', () => {
          isActive = false;
          setStatus('Disconnected', false);
          $('trillet-v-label').textContent = 'Call ended';
          $('trillet-v-vis').classList.remove('active');
          showIdleControls();
          stopPolling();
          addMsg('Call ended', 'system');
        });

        agent.on('error', () => {
          addMsg('An error occurred', 'system');
          setStatus('Error', false);
        });

        agent.on('assistantStartedSpeaking', () => {
          $('trillet-v-label').textContent = 'Agent speaking...';
        });

        agent.on('assistantStoppedSpeaking', () => {
          $('trillet-v-label').textContent = isMuted ? 'Muted' : 'Listening...';
        });

        ['message', 'transcript', 'transcriptUpdate'].forEach(evt => {
          agent.on(evt, (data) => {
            if (data?.isFinal === false) return;
            const text = typeof data === 'string' ? data : data?.text || data?.content;
            const role = data?.role || 'assistant';
            if (text) addMsg(text, role);
          });
        });

        await agent.startPublicCall();
      } catch (err) {
        setStatus('Failed', false);
        $('trillet-v-label').textContent = 'Failed to connect';
        $('trillet-v-mic').disabled = false;
        showIdleControls();
      }
    }

    function toggleMute() {
      isMuted = !isMuted;
      try { agent?.toggleMicrophone?.(!isMuted); } catch (e) {}
      const mic = $('trillet-v-mic');
      if (isMuted) {
        mic.className = 'trillet-v-mic muted';
        mic.innerHTML = micMutedSvg;
        $('trillet-v-label').textContent = 'Muted';
      } else {
        mic.className = 'trillet-v-mic active';
        mic.innerHTML = micSvg;
        $('trillet-v-label').textContent = 'Listening...';
      }
    }

    function endCall() { try { agent?.endCall(); } catch (e) {} }

    function showActiveControls() {
      $('trillet-v-btns').innerHTML = `
        <button class="trillet-v-end" id="trillet-v-end">${hangupSvg}</button>
        <button class="trillet-v-mic active" id="trillet-v-mic">${micSvg}</button>
      `;
      $('trillet-v-end').addEventListener('click', endCall);
      $('trillet-v-mic').addEventListener('click', toggleMute);
    }

    function showIdleControls() {
      $('trillet-v-btns').innerHTML = `
        <button class="trillet-v-mic idle" id="trillet-v-mic">${micSvg}</button>
      `;
      $('trillet-v-mic').addEventListener('click', () => {
        if (!isActive) connectAgent();
        else toggleMute();
      });
    }

    function startPolling() {
      let lastCount = 0;
      pollInterval = setInterval(() => {
        if (!agent || !isActive) return;
        try {
          const transcripts = agent.getTranscripts?.() || [];
          for (let i = lastCount; i < transcripts.length; i++) {
            const t = transcripts[i];
            if (t.text) addMsg(t.text, t.role || 'assistant');
          }
          lastCount = transcripts.length;
        } catch (e) {}
      }, 500);
    }

    function stopPolling() {
      if (pollInterval) { clearInterval(pollInterval); pollInterval = null; }
    }

    function setStatus(text, online) {
      $('trillet-v-status-text').textContent = text;
      $('trillet-v-dot').classList.toggle('online', online);
    }

    function addMsg(text, type) {
      if (!text?.trim()) return;
      const key = type + ':' + text;
      if (displayed.has(key)) return;
      displayed.add(key);
      const el = document.createElement('div');
      el.className = 'trillet-v-msg ' + type;
      el.textContent = text;
      const container = $('trillet-v-transcript');
      container.appendChild(el);
      container.scrollTop = container.scrollHeight;
    }
  </script>

</body>
</html>
```
    </Tab>
    <Tab title="React / Next.js">
```bash
npm install @trillet-ai/web-sdk
```

```tsx
import { useRef, useState, useEffect, useCallback } from 'react';
import { TrilletAgent } from '@trillet-ai/web-sdk';

export default function TrilletVoice({ workspaceId, agentId }) {
  const agentRef = useRef(null);
  const [isOpen, setIsOpen] = useState(false);
  const [isActive, setIsActive] = useState(false);
  const [isMuted, setIsMuted] = useState(false);
  const [status, setStatus] = useState('idle');
  const [label, setLabel] = useState('Tap the mic to start');
  const [transcripts, setTranscripts] = useState([]);

  const startCall = useCallback(async () => {
    const agent = new TrilletAgent({ workspaceId, agentId, mode: 'voice' });
    agentRef.current = agent;
    setStatus('connecting');
    setLabel('Connecting...');

    agent.on('connected', () => {
      setIsActive(true); setStatus('connected'); setLabel('Listening...');
      let lastCount = 0;
      const poll = setInterval(() => {
        const t = agent.getTranscripts?.() || [];
        for (let i = lastCount; i < t.length; i++) {
          if (t[i].text) setTranscripts(prev => [...prev, { type: t[i].role || 'assistant', text: t[i].text }]);
        }
        lastCount = t.length;
      }, 500);
      agent.__poll = poll;
    });
    agent.on('disconnected', () => {
      setIsActive(false); setStatus('idle'); setLabel('Call ended'); setIsMuted(false);
      clearInterval(agent.__poll);
    });
    agent.on('assistantStartedSpeaking', () => setLabel('Agent speaking...'));
    agent.on('assistantStoppedSpeaking', () => setLabel(prev => prev === 'Muted' ? 'Muted' : 'Listening...'));
    agent.on('error', () => setStatus('error'));

    ['message', 'transcript'].forEach(evt => {
      agent.on(evt, (data) => {
        const text = typeof data === 'string' ? data : data?.text || data?.content;
        const role = data?.role || 'assistant';
        if (text) setTranscripts(prev => [...prev, { type: role, text }]);
      });
    });

    try { await agent.startPublicCall(); }
    catch { setStatus('error'); setLabel('Failed to connect'); }
  }, [workspaceId, agentId]);

  const endCall = () => agentRef.current?.endCall();

  const toggleMute = () => {
    const next = !isMuted;
    setIsMuted(next);
    setLabel(next ? 'Muted' : 'Listening...');
    agentRef.current?.toggleMicrophone?.(!next);
  };

  useEffect(() => () => agentRef.current?.endCall?.(), []);

  const s = {
    bubble: { position: 'fixed', bottom: 24, right: 24, width: 52, height: 52,
      borderRadius: 12, background: '#0066ff', border: '1px solid rgba(0,102,255,0.2)',
      cursor: 'pointer', color: '#fff', display: 'flex', alignItems: 'center',
      justifyContent: 'center', zIndex: 9999, boxShadow: '0 1px 3px rgba(0,0,0,0.08)' },
    panel: { position: 'fixed', bottom: 88, right: 24, width: 340,
      background: '#fff', borderRadius: 12, border: '1px solid #e5e7eb',
      boxShadow: '0 4px 12px -1px rgba(0,0,0,0.05)',
      display: 'flex', flexDirection: 'column', zIndex: 9999,
      fontFamily: '-apple-system, BlinkMacSystemFont, system-ui, sans-serif' },
  };

  return (
    <>
      <button onClick={() => setIsOpen(!isOpen)} style={s.bubble}>
        <svg width="22" height="22" fill="#fff" viewBox="0 0 24 24"><path d="M12 14c1.66 0 3-1.34 3-3V5c0-1.66-1.34-3-3-3S9 3.34 9 5v6c0 1.66 1.34 3 3 3zm-1-9c0-.55.45-1 1-1s1 .45 1 1v6c0 .55-.45 1-1 1s-1-.45-1-1V5zm6 6c0 2.76-2.24 5-5 5s-5-2.24-5-5H5c0 3.53 2.61 6.43 6 6.92V21h2v-3.08c3.39-.49 6-3.39 6-6.92h-2z"/></svg>
      </button>
      {isOpen && (
        <div style={s.panel}>
          <div style={{ padding: '14px 16px', borderBottom: '1px solid #e5e7eb',
            display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
            <div>
              <div style={{ fontWeight: 600, fontSize: 14, color: '#111827' }}>Voice Assistant</div>
              <div style={{ fontSize: 12, color: status === 'connected' ? '#10b981' : '#6b7280' }}>
                {status === 'connected' ? 'Connected' : status === 'connecting' ? 'Connecting...' : 'Ready'}
              </div>
            </div>
            <button onClick={() => setIsOpen(false)}
              style={{ background: 'none', border: 'none', color: '#9ca3af', cursor: 'pointer', fontSize: 16 }}>
              &#x2715;
            </button>
          </div>
          {transcripts.length > 0 && (
            <div style={{ maxHeight: 180, overflowY: 'auto', padding: '12px 16px',
              display: 'flex', flexDirection: 'column', gap: 6, background: '#f9fafb' }}>
              {transcripts.map((t, i) => (
                <div key={i} style={{ alignSelf: t.type === 'user' ? 'flex-end' : 'flex-start',
                  background: t.type === 'user' ? '#0066ff' : '#fff',
                  color: t.type === 'user' ? '#fff' : '#111827',
                  border: t.type === 'user' ? 'none' : '1px solid #e5e7eb',
                  padding: '7px 11px', borderRadius: 8, maxWidth: '85%', fontSize: 12 }}>
                  {t.text}
                </div>
              ))}
            </div>
          )}
          <div style={{ padding: 20, borderTop: '1px solid #e5e7eb', display: 'flex',
            flexDirection: 'column', alignItems: 'center', gap: 14 }}>
            <div style={{ fontSize: 12, color: '#6b7280', fontWeight: 500 }}>{label}</div>
            <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
              {isActive && (
                <button onClick={endCall}
                  style={{ width: 40, height: 40, borderRadius: 12, background: '#ef4444',
                    border: '1px solid rgba(239,68,68,0.2)', color: '#fff', cursor: 'pointer',
                    display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
                  &#x260E;
                </button>
              )}
              <button onClick={isActive ? toggleMute : startCall}
                disabled={status === 'connecting'}
                style={{ width: 48, height: 48, borderRadius: 12, cursor: 'pointer',
                  display: 'flex', alignItems: 'center', justifyContent: 'center',
                  background: isMuted ? '#fef2f2' : '#0066ff',
                  color: isMuted ? '#ef4444' : '#fff',
                  border: `1px solid ${isMuted ? 'rgba(239,68,68,0.15)' : 'rgba(0,102,255,0.2)'}`,
                  boxShadow: '0 1px 3px rgba(0,0,0,0.08)' }}>
                {isMuted ? '🔇' : '🎙️'}
              </button>
            </div>
          </div>
        </div>
      )}
    </>
  );
}
```

Usage:
```tsx
<TrilletVoice workspaceId="your-workspace-id" agentId="your-agent-id" />
```
    </Tab>
  </Tabs>
</Accordion>

## Events Reference

| Event | Description |
|---|---|
| `connected` | Voice call connected, agent is live |
| `disconnected` | Call ended |
| `error` | An error occurred |
| `assistantStartedSpeaking` | Agent is speaking |
| `assistantStoppedSpeaking` | Agent stopped speaking |
| `transcript` | Transcript of speech (user or assistant) |

```js
agent.on('assistantStartedSpeaking', () => {
  console.log('Agent is talking...');
});
```

---

## Authentication

*Learn how to authenticate your API requests*

All API endpoints require authentication using Bearer tokens in the Authorization header:

```bash
curl https://api.trillet.ai/v1/api/
  -H "x-api-key: YOUR_API_KEY"
  -H "Content-Type: application/json"
```
<ParamField header="x-api-key" type="string" required>
  API key used for authenticating requests to the API. This key must be included in the header of each request.
</ParamField>
<ParamField header="x-workspace-id" type="string">
  Workspace identifier for the API.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`.
</ParamField>

## Obtaining API Keys

Generate an API key under the 'Settings' tab for your API credentials. Each API key has specific permissions and limits associated with it.

<Note>
  Get your API key from [Trillet Settings Dashboard](https://app.trillet.ai/settings)
</Note>

## Security Best Practices

1. Keep your API keys secure and never expose them in client-side code
2. Rotate your API keys periodically
3. Use different API keys for development and production environments
4. Monitor your API key usage for any suspicious activity

---

## API Endpoints

*Complete reference for all Trillet AI API endpoints*

## Agents

Virtual AI assistants that handle voice interactions.

### Create Agent

<ParamField path="POST /api/v1/agents">
  Create a new AI agent by selecting voice model characteristics and the
  underlying language model for script execution.
</ParamField>

### List Agents

<ParamField path="GET /api/v1/agents">
  Retrieve a paginated list of all available agents in your account.
</ParamField>

### Get Agent

<ParamField path="GET /api/v1/agents/{agentId}">
  Fetch detailed configuration and status information for a specific agent.
</ParamField>

### Update Agent

<ParamField path="PATCH /api/v1/agents/{agentId}">
  Modify an existing agent's properties like name, voice settings, or
  personality.
</ParamField>

### Delete Agent

<ParamField path="DELETE /api/v1/agents/{agentId}">
  Permanently remove an agent from your account.
</ParamField>

## Flows

Complex flows that define how agents handle calls and route conversations.

### Create Flow

<ParamField path="POST /api/v1/flows">
  Create a new call flow by defining flows for call handling and routing
  logic.
</ParamField>

### List Flows

<ParamField path="GET /api/v1/flows">
  Get a paginated list of all call flows in your account.
</ParamField>

### Get Flow

<ParamField path="GET /api/v1/flows/{flowId}">
  Retrieve detailed configuration for a specific call flow including routing
  logic.
</ParamField>

### Update Flow

<ParamField path="PATCH /api/v1/flows/{flowId}">
  Modify an existing call flow and routing rules.
</ParamField>

### Delete Flow

<ParamField path="DELETE /api/v1/flows/{flowId}">
  Permanently remove a call flow from your account.
</ParamField>

## Calls

Manage outbound voice calls using agents and flows.

### Send Call

<ParamField path="POST /api/v1/calls/call">
  Initiate a new outbound call using an AI agent.
</ParamField>

#### Request Body

<ResponseField name="agentId" type="string" required>
  The unique identifier of the AI agent that will handle the call
</ResponseField>

<ResponseField name="toNumber" type="string" required>
  The phone number to call in E.164 format (e.g., +1234567890)
</ResponseField>

#### Response

<ResponseField name="status" type="string">
  Will be "success" if the call was initiated successfully
</ResponseField>

<ResponseField name="callId" type="string">
  A unique identifier for the call
</ResponseField>

<ResponseField name="roomName" type="string">
  Internal room identifier for the call session
</ResponseField>

<ResponseField name="fromNumber" type="string">
  The phone number the call will be placed from
</ResponseField>

<ResponseField name="toNumber" type="string">
  The destination phone number
</ResponseField>

<ResponseField name="agent" type="object">
  <Expandable title="Agent Details">
    <ResponseField name="id" type="string">
      The agent's unique identifier
    </ResponseField>
    <ResponseField name="name" type="string">
      The name of the agent
    </ResponseField>
    <ResponseField name="model" type="string">
      The AI model being used (e.g., "gpt-4o-mini")
    </ResponseField>
    <ResponseField name="voice" type="object">
      Voice configuration details
    </ResponseField>
  </Expandable>
</ResponseField>

#### Example Response

```json
{
  "status": "success",
  "callId": "ab12cd34ef",
  "roomName": "64f8e3b1c12d8e9a4f3c2d1e-ab12cd34ef",
  "fromNumber": "+1987654321",
  "toNumber": "+1234567890",
  "agent": {
    "id": "64f8e3b1c12d8e9a4f3c2d1e",
    "name": "Sales Assistant",
    "model": "gpt-4o-mini",
    "voice": {
      "provider": "openai",
      "voiceId": "alloy"
    }
  }
}
```

#### Error Responses

<ResponseField name="404 - Not Found">
```json
{
  "error": "Agent not found",
  "details": "The specified agent does not exist or you don't have access to it"
}
```
</ResponseField>

<ResponseField name="400 - Bad Request">
```json
{
  "error": "Invalid configuration",
  "details": "Agent has no phone number configured"
}
```
</ResponseField>

<ResponseField name="500 - Internal Server Error">
```json
{
  "error": "Failed to initiate call",
  "details": "Error message",
  "code": "UNKNOWN_ERROR"
}
```
</ResponseField>

#### Notes

- The agent must have an active phone number configured
- The agent must have an active flow configured
- All phone numbers should be in E.164 format (+[country code][number])
- Calls are recorded by default unless specified otherwise
- Maximum call duration is typically 1 hour

## Batch Calls

Efficiently make multiple AI-powered calls using CSV data uploads.

### Download CSV Template

<ParamField path="GET /v1/api/batch-calls/template">
  Download a properly formatted CSV template for batch call operations.
</ParamField>

### Validate CSV

<ParamField path="POST /v1/api/batch-calls/validate">
  Validate a CSV file and preview the data before starting batch calls.
</ParamField>

### Preview CSV Data

<ParamField path="POST /v1/api/batch-calls/preview">
  Preview the data from a CSV file to verify formatting and content.
</ParamField>

### Start Batch Operation

<ParamField path="POST /v1/api/batch-calls">
  Initiate a batch call operation using a CSV file and specified agent.
</ParamField>

### Get Batch Status

<ParamField path="GET /v1/api/batch-calls/{batchId}">
  Get detailed status information for a batch call operation.
</ParamField>

### Get Batch Progress

<ParamField path="GET /v1/api/batch-calls/{batchId}/status">
  Get real-time progress information for a batch call operation.
</ParamField>

### List Batch Calls

<ParamField path="GET /v1/api/batch-calls/{batchId}/calls">
  Get a paginated list of all calls within a batch operation with filtering.
</ParamField>

### Get Individual Call Status

<ParamField path="GET /v1/api/batch-calls/{batchId}/calls/{jobId}">
  Get the status of an individual call within a batch operation.
</ParamField>

### Cancel Batch Operation

<ParamField path="DELETE /v1/api/batch-calls/{batchId}">
  Cancel a batch call operation and stop remaining calls from processing.
</ParamField>

---

## API Reference

*Complete reference for the Trillet AI Platform API*

## Overview

The Trillet AI API provides programmatic access to create and manage AI agents, conversation flows, voice calls, and SMS messaging. Our REST API uses standard HTTP methods and returns JSON responses.

<Card title="Base URL" icon="globe">
  ```bash https://api.trillet.ai ```
</Card>

## Authentication

All API requests require authentication using an API key in the `x-api-key` header:

```bash
curl https://api.trillet.ai/v1/api/
  -H "x-api-key: YOUR_API_KEY"
  -H "Content-Type: application/json"
```

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication. Include this in the request headers.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`.
</ParamField>

<Note>
  Get your API key from [Trillet Settings
  Dashboard](https://app.trillet.ai/settings)
</Note>

## API Resources

<Columns cols={2}>
  <Card
    title="Call Agents API"
    icon="robot"
    href="/v1/api-reference/endpoints/agents/call/create"
  >
    Create and manage conversational call agents with unique voices and
    personalities through our REST API
  </Card>
  <Card
    title="Omni Flow Agents API"
    icon="message-bot"
    href="/v1/api-reference/endpoints/agents/omniflow/create"
  >
    Create and manage messaging AI agents with unique through our REST API
  </Card>
  <Card
    title="Call Flows API"
    icon="diagram-project"
    href="/v1/api-reference/endpoints/flows/call-flows/create"
  >
    Design and control call & conversation flows programmatically
  </Card>
  <Card
    title="Message Flows API"
    icon="message-code"
    href="/v1/api-reference/endpoints/flows/message-flows/create"
  >
    Design and control call & conversation flows programmatically
  </Card>
  <Card
    title="Voice Calls API"
    icon="phone"
    href="/v1/api-reference/endpoints/calls/initiate-call"
  >
    Initiate and manage voice calls via REST endpoints
  </Card>
  <Card
    title="Conversations API"
    icon="comments"
    href="/v1/api-reference/endpoints/conversations/generateMessage"
  >
    Design and control customer interactions through conversations
    programmatically
  </Card>
</Columns>

## Rate Limits

<Info>
  The API has rate limits based on your plan. Contact the Trillet team to
  increase your limits.
</Info>

| Plan      | Requests per minute | Concurrent calls |
| --------- | ------------------- | ---------------- |
| Developer | 60                  | 1                |

## Webhooks [Coming Soon!]

Configure webhooks to receive real-time updates about events in your account. Each webhook request includes an event type and relevant data:

```json
{
  "event": "call.completed",
  "data": {
    "callId": "call_xyz789",
    "agentId": "agent_123abc",
    "duration": 125,
    "status": "completed"
  }
}
```

### Webhook Events

- `call.started` - When a call begins
- `call.completed` - When a call ends
- `call.failed` - When a call fails to connect
- `sms.sent` - When an SMS is sent
- `sms.delivered` - When an SMS is delivered
- `agent.created` - When a new agent is created
- `agent.updated` - When an agent is updated
- `flow.created` - When a new flow is created
- `flow.updated` - When a flow is updated

### Webhook Security

Verify webhook signatures using the signature in the `X-Trillet-Signature` header:

```bash
# Your webhook secret from the dashboard
WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx

# Verify the signature before processing webhooks
```

## Error Handling

The API uses conventional HTTP response codes:

- `200` - Success
- `400` - Bad request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not found
- `429` - Too many requests
- `500` - Server error

Error responses include a message and error code:

```json
{
  "error": {
    "code": "invalid_number",
    "message": "The provided phone number is invalid"
  }
}
```

## Need Help?

<Columns cols={2}>
  <Card title="API Status [Coming Soon!]" icon="signal">
    Check our API status and uptime
  </Card>
  <Card title="Support" icon="headset" href="mailto:support@trillet.ai">
    Get technical support
  </Card>
</Columns>

---

## End Active Call

*End an active call by its room name.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="roomName" type="string" required>
The LiveKit room name of the active call to end.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the call was ended successfully.
</ResponseField>

<ResponseField name="message" type="string">
Confirmation message.
</ResponseField>

<ResponseField name="roomName" type="string">
The room name of the ended call.
</ResponseField>

<ResponseField name="endTime" type="string">
ISO timestamp when the call was ended.
</ResponseField>

<ResponseExample>
```json
{
  "success": true,
  "message": "Call ended successfully",
  "roomName": "call-abc123",
  "endTime": "2024-06-01T10:05:00.000Z"
}
```
</ResponseExample>

---

## Get Call Insights

*Get AI-generated insights for an active call, including sentiment analysis and key topics.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="roomName" type="string" required>
The LiveKit room name of the active call.
</ParamField>

## Response Fields

<ResponseField name="sentiment" type="string">
Overall sentiment of the conversation (e.g., "positive", "neutral", "negative").
</ResponseField>

<ResponseField name="topics" type="array">
Key topics discussed in the call.
</ResponseField>

<ResponseField name="summary" type="string">
AI-generated summary of the conversation so far.
</ResponseField>

<ResponseField name="suggestions" type="array">
AI-generated suggestions for the agent.
</ResponseField>

<ResponseExample>
```json
{
  "sentiment": "positive",
  "topics": ["account inquiry", "billing"],
  "summary": "Customer is asking about their recent invoice and payment options.",
  "suggestions": [
    "Offer to email a detailed invoice breakdown",
    "Mention the available payment plans"
  ]
}
```
</ResponseExample>

---

## Get Active Call Details

*Retrieve detailed information about a specific active call including participants, transcript, and sentiment.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="roomName" type="string" required>
The LiveKit room name of the active call.
</ParamField>

## Response Fields

<ResponseField name="id" type="string">
Unique identifier for the active call.
</ResponseField>

<ResponseField name="roomName" type="string">
The LiveKit room name.
</ResponseField>

<ResponseField name="customerPhone" type="string">
Customer's phone number.
</ResponseField>

<ResponseField name="customerName" type="string">
Customer's name if available.
</ResponseField>

<ResponseField name="aiAgentName" type="string">
Name of the AI agent handling the call.
</ResponseField>

<ResponseField name="duration" type="number">
Current call duration in seconds.
</ResponseField>

<ResponseField name="sentiment" type="string">
Current detected sentiment.
</ResponseField>

<ResponseField name="transcript" type="array">
Live transcript of the conversation.
</ResponseField>

<ResponseField name="participants" type="array">
Array of call participants with metadata.
</ResponseField>

<ResponseExample>
```json
{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "roomName": "call-abc123",
  "customerPhone": "+14155551234",
  "customerName": "John Doe",
  "aiAgentName": "Customer Support Agent",
  "duration": 145,
  "sentiment": "positive",
  "transcript": [
    { "role": "agent", "content": "Hello! How can I help you today?" },
    { "role": "customer", "content": "I need help with my account." }
  ],
  "participants": [
    {
      "identity": "agent-001",
      "isAgent": true,
      "metadata": {},
      "joinedAt": "2024-06-01T10:00:00.000Z"
    }
  ]
}
```
</ResponseExample>

---

## List Active Calls

*Retrieve all currently active calls in your workspace with real-time status information.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Response Fields

<ResponseField name="data" type="array">
Array of active call objects.

<ResponseField name="id" type="string">
Unique identifier for the active call.
</ResponseField>

<ResponseField name="roomName" type="string">
The LiveKit room name for the call.
</ResponseField>

<ResponseField name="customerPhone" type="string">
Customer's phone number.
</ResponseField>

<ResponseField name="customerName" type="string">
Customer's name if available.
</ResponseField>

<ResponseField name="aiAgentName" type="string">
Name of the AI agent handling the call.
</ResponseField>

<ResponseField name="duration" type="number">
Current call duration in seconds.
</ResponseField>

<ResponseField name="status" type="string">
Call status (always "active" for this endpoint).
</ResponseField>

<ResponseField name="sentiment" type="string">
Current detected sentiment of the conversation.
</ResponseField>

<ResponseField name="lastMessage" type="string">
The most recent message in the conversation.
</ResponseField>

<ResponseField name="transferRequested" type="boolean">
Whether a transfer to a human agent has been requested.
</ResponseField>

<ResponseField name="type" type="string">
Call type: "phone" or "web".
</ResponseField>

<ResponseField name="participants" type="array">
Array of call participants.
</ResponseField>

</ResponseField>

<ResponseField name="count" type="number">
Total number of active calls.
</ResponseField>

<ResponseField name="timestamp" type="string">
Server timestamp of the response.
</ResponseField>

<ResponseExample>
```json
{
  "data": [
    {
      "id": "665a1b2c3d4e5f6a7b8c9d0e",
      "roomName": "call-abc123",
      "customerPhone": "+14155551234",
      "customerName": "John Doe",
      "aiAgentName": "Customer Support Agent",
      "duration": 145,
      "status": "active",
      "sentiment": "positive",
      "lastMessage": "Sure, I can help you with that!",
      "transferRequested": false,
      "type": "phone",
      "participants": [
        {
          "identity": "agent-001",
          "isAgent": true,
          "joinedAt": "2024-06-01T10:00:00.000Z"
        },
        {
          "identity": "customer-001",
          "isAgent": false,
          "joinedAt": "2024-06-01T10:00:01.000Z"
        }
      ]
    }
  ],
  "count": 1,
  "timestamp": "2024-06-01T10:02:25.000Z"
}
```
</ResponseExample>

---

## Remove AI Agent (Human Takeover)

*Remove the AI agent from an active call to allow human takeover. The agent is muted rather than disconnected.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="roomName" type="string" required>
The LiveKit room name of the active call.
</ParamField>

## Request Body

<ParamField body="participantIdentity" type="string" required>
Identity of the AI agent participant to remove/mute.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the agent was removed successfully.
</ResponseField>

<ResponseField name="message" type="string">
Confirmation message.
</ResponseField>

<ResponseField name="roomName" type="string">
The room name of the call.
</ResponseField>

<ResponseField name="mutedTracks" type="array">
Array of track SIDs that were muted.
</ResponseField>

<ResponseExample>
```json
{
  "success": true,
  "message": "Agent removed from call",
  "roomName": "call-abc123",
  "mutedTracks": ["TR_abc123"]
}
```
</ResponseExample>

---

## Create API Key

*Generate a new API key for authenticating requests to the Trillet API.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
The unique identifier of the workspace being accessed.
</ParamField>

## Request Body

<ParamField body="metadata" type="object">
Optional metadata to associate with the API key.
</ParamField>

## Response Fields

<ResponseField name="key" type="string">
The generated 32-character API key. Store this securely as it cannot be retrieved again.
</ResponseField>

<ResponseField name="_id" type="string">
Unique identifier for the API key record.
</ResponseField>

<ResponseField name="userId" type="string">
User ID associated with the API key.
</ResponseField>

<ResponseField name="metadata" type="object">
Metadata associated with the API key.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the API key was created.
</ResponseField>

<ResponseExample>
```json
{
  "key": "tk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "userId": "664a1b2c3d4e5f6a7b8c9d0e",
  "metadata": {},
  "createdAt": "2024-06-01T09:00:00.000Z"
}
```
</ResponseExample>

---

## Delete API Key

*Delete an API key. The key will immediately stop working for authentication.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
The unique identifier of the workspace being accessed.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique identifier of the API key to delete.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the deletion was successful.
</ResponseField>

<ResponseExample>
```json
{
  "success": true
}
```
</ResponseExample>

---

## List API Keys

*Retrieve all API keys for the authenticated user.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
The unique identifier of the workspace being accessed.
</ParamField>

## Response Fields

<ResponseField name="keys" type="array">
Array of API key objects.

<ResponseField name="_id" type="string">
Unique identifier for the API key.
</ResponseField>

<ResponseField name="key" type="string">
The API key (partially masked for security).
</ResponseField>

<ResponseField name="userId" type="string">
User ID associated with the API key.
</ResponseField>

<ResponseField name="metadata" type="object">
Metadata associated with the API key.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the API key was created.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
[
  {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "key": "tk_a1b2****o5p6",
    "userId": "664a1b2c3d4e5f6a7b8c9d0e",
    "metadata": {},
    "createdAt": "2024-06-01T09:00:00.000Z"
  }
]
```
</ResponseExample>

---

## Delete Call Disposition

*Delete or cancel a call disposition.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique identifier of the call disposition to delete.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the deletion was successful.
</ResponseField>

<ResponseExample>
```json
{
  "success": true
}
```
</ResponseExample>

---

## Export Call Dispositions CSV

*Export call dispositions as a CSV file.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Query Parameters

<ParamField query="phoneNumber" type="string">
Filter by phone number.
</ParamField>

<ParamField query="batchId" type="string">
Filter by batch call ID.
</ParamField>

<ParamField query="agentId" type="string">
Filter by agent ID.
</ParamField>

<ParamField query="status" type="string">
Filter by disposition status.
</ParamField>

<ParamField query="disposition" type="string">
Filter by disposition type.
</ParamField>

<ParamField query="timezone" type="string">
Timezone for date formatting in the CSV.
</ParamField>

## Response

The response is a CSV file with `Content-Type: text/csv` headers containing all matching dispositions with columns for phone number, disposition type, status, scheduled time, attempt number, agent, and notes.

---

## Get Call Disposition

*Retrieve a specific call disposition by its ID.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique identifier of the call disposition.
</ParamField>

## Response Fields

<ResponseField name="_id" type="string">
Unique identifier for the disposition.
</ResponseField>

<ResponseField name="phoneNumber" type="string">
Phone number associated with the disposition.
</ResponseField>

<ResponseField name="disposition" type="string">
Disposition type (e.g., "callback_scheduled", "no_answer", "completed").
</ResponseField>

<ResponseField name="status" type="string">
Current status of the disposition.
</ResponseField>

<ResponseField name="scheduledAt" type="string">
Scheduled callback time (if applicable).
</ResponseField>

<ResponseField name="attempt" type="number">
Attempt number for this call.
</ResponseField>

<ResponseField name="agentId" type="string">
Agent ID that handled the call.
</ResponseField>

<ResponseField name="batchId" type="string">
Batch call ID (if part of a batch).
</ResponseField>

<ResponseField name="notes" type="string">
Any notes from the call or disposition.
</ResponseField>

<ResponseExample>
```json
{
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "phoneNumber": "+14155551234",
  "disposition": "callback_scheduled",
  "status": "pending",
  "scheduledAt": "2024-06-02T14:00:00.000Z",
  "attempt": 1,
  "agentId": "665a1b2c3d4e5f6a7b8c9d0f",
  "batchId": "665a1b2c3d4e5f6a7b8c9d10",
  "notes": "Customer requested callback after 2pm",
  "createdAt": "2024-06-01T10:00:00.000Z"
}
```
</ResponseExample>

---

## List Call Dispositions

*Retrieve a paginated list of call dispositions with filtering options.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Query Parameters

<ParamField query="page" type="number" default="1">
Page number for pagination.
</ParamField>

<ParamField query="limit" type="number" default="50">
Number of records per page.
</ParamField>

<ParamField query="phoneNumber" type="string">
Filter by phone number.
</ParamField>

<ParamField query="batchId" type="string">
Filter by batch call ID.
</ParamField>

<ParamField query="agentId" type="string">
Filter by agent ID.
</ParamField>

<ParamField query="status" type="string">
Filter by disposition status.
</ParamField>

<ParamField query="disposition" type="string">
Filter by disposition type.
</ParamField>

<ParamField query="attempt" type="number">
Filter by attempt number.
</ParamField>

<ParamField query="search" type="string">
Search across dispositions.
</ParamField>

<ParamField query="timezone" type="string">
Timezone for date formatting (e.g., "America/New_York").
</ParamField>

## Response Fields

<ResponseField name="data" type="object">
Paginated disposition data.

<ResponseField name="dispositions" type="array">
Array of call disposition objects.
</ResponseField>

<ResponseField name="total" type="number">
Total number of matching dispositions.
</ResponseField>

<ResponseField name="page" type="number">
Current page number.
</ResponseField>

<ResponseField name="limit" type="number">
Records per page.
</ResponseField>

<ResponseField name="totalPages" type="number">
Total number of pages.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
{
  "data": {
    "dispositions": [
      {
        "_id": "665a1b2c3d4e5f6a7b8c9d0e",
        "phoneNumber": "+14155551234",
        "disposition": "callback_scheduled",
        "status": "pending",
        "scheduledAt": "2024-06-02T14:00:00.000Z",
        "attempt": 1,
        "agentId": "665a1b2c3d4e5f6a7b8c9d0f",
        "batchId": "665a1b2c3d4e5f6a7b8c9d10",
        "createdAt": "2024-06-01T10:00:00.000Z"
      }
    ],
    "total": 25,
    "page": 1,
    "limit": 50,
    "totalPages": 1
  }
}
```
</ResponseExample>

---

## Update Call Disposition

*Update a call disposition, such as rescheduling a callback.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique identifier of the call disposition to update.
</ParamField>

## Request Body

<ParamField body="scheduledAt" type="string">
New scheduled callback time in ISO format.
</ParamField>

<ParamField body="status" type="string">
Updated status for the disposition.
</ParamField>

<ParamField body="notes" type="string">
Updated notes for the disposition.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the update was successful.
</ResponseField>

<ResponseField name="disposition" type="object">
The updated disposition object.
</ResponseField>

<ResponseExample>
```json
{
  "success": true,
  "disposition": {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "phoneNumber": "+14155551234",
    "disposition": "callback_scheduled",
    "status": "pending",
    "scheduledAt": "2024-06-03T10:00:00.000Z",
    "attempt": 1
  }
}
```
</ResponseExample>

---

## Get Call Recording

*Retrieve audio recording for a completed call session.*

### Headers  
<ParamField header="x-workspace-id" type="string" required>
The unique identifier of the workspace being accessed.
</ParamField>


### Path Parameters

<ParamField path="callSid" type="string" required>
  The Twilio Call SID of the call whose recording you want.
</ParamField>

### Response Fields

<ResponseField name="Content-Type" type="string">
  Indicates the MIME type of the streamed content, which is 'audio/mpeg' for MP3 audio files.
</ResponseField>

<ResponseField name="Content-Disposition" type="string">
  Describes how the content should be handled by the browser; set to 'inline' with a filename indicating the name of the downloaded or played file.
</ResponseField>

### Response

An audio/mpeg file (MP3) is streamed back. You can download or play it in the browser.

<ResponseExample>
  ```json 
  HTTP/1.1 200 OK 
  Content-Type: audio/mpeg 
  Content-Disposition: inline;
  filename="exampleRecordingSid.mp3" 
  ```
</ResponseExample>

---

## Initiate Outbound Call

*Send an AI-driven phone call to a given number.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Request Body

<ParamField body="to" type="string" required>
  The phone number to which the call will be made.
</ParamField>

<ParamField body="call_agent_id" type="string" required>
  The ID of the agent assigned to make the call.
</ParamField>

<ParamField body="callback_url" type="string" optional>
  A URL to receive webhook events about the call. If provided, this URL will be used for notifications.
</ParamField>

<ParamField body="dynamic_variables" type="object">
  Dynamic variables that can be used to customize call scripts. Each key represents a variable that can be inserted into the call script dynamically. For example:

  <Expandable title="Dynamic Variables Details">
    <ParamField body="firstName" type="string">
      First name of the person to address in the call.
    </ParamField>
    <ParamField body="lastName" type="string">
      Last name of the person.
    </ParamField>
    <ParamField body="Zipcode" type="string">
      Zip code for regional customization or information.
    </ParamField>
    <ParamField body="address" type="string">
      Full address for detailed directions or service customization.
    </ParamField>
    <ParamField body="email" type="string">
      Email address to reference or verify during the call.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object" optional>
  Any fields passed here will be sent to the call agent and directly passed to the webhook triggered by the agent under its 'metadata' header, but they will not be included in the call agent's context.
  <Expandable title="Metadata Details">
    
  </Expandable>
</ParamField>



### Response Fields

<ResponseField name="status" type="string">
  The status of the request, indicating the success or failure of the call initiation.
</ResponseField>

<ResponseField name="message" type="string">
  A message providing feedback about the call initiation process, typically confirming successful initiation or describing an error.
</ResponseField>

<ResponseField name="callId" type="string">
  A unique identifier assigned to the initiated call. This ID can be used to track the call's progress or retrieve its details later.
</ResponseField>

<ResponseField name="roomName" type="string">
  The name of the LiveKit room created for this call session.
</ResponseField>

<ResponseField name="jobId" type="string">
  The identifier of the background job scheduled to execute the outbound call.
</ResponseField>

<ResponseExample>
```json
{
  "status": "success",
  "message": "Outbound call job scheduled for agent a1b2c3d4e5f6a7b8c9d0e1f2 to number +1234567890",
  "callId": "f9e8d7c6b5a4f3e2d1c0b9a8",
  "roomName": "a1b2c3d4e5f6a7b8c9d0e1f2-x7k2m9p4q1",
  "jobId": "123"
}
```
</ResponseExample>

---

## Delete Conversation

*Delete a conversation from the database.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters
<ParamField path="conversationId" type="string" required>
  The Conversation ID of the conversation you want to delete.
</ParamField>

### Response Fields

<ResponseField name="status" type="string">
  The status of the call.
</ResponseField>

<ResponseField name="message" type="string">
  A message to describe the result.
</ResponseField>

<ResponseField name="conversationId" type="string">
  The deleted conversationId.
</ResponseField>

<ResponseExample>
```json
{
"status": "success",
"message": `Conversation with ID abc1234aa deleted successfully.`,
"conversationId": abc1234aa,
}
```
</ResponseExample>

---

## Delete Message

*Delete a message in a specific conversation from the database.*

### Headers  
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField body="conversationId" type="string" required>
  The unique identifier for the conversation containing the message.
</ParamField>

<ParamField body="messageId" type="string" required>
  The unique identifier for the message to be deleted.
</ParamField>

<ParamField type="string" body="" default="s" optional hidden>
  An optional, empty object as the default body.
</ParamField>


### Response Fields

<ResponseField name="status" type="string">
  The status of the call.
</ResponseField>

<ResponseField name="message" type="string">
  A message to describe the result.
</ResponseField>

<ResponseField name="conversationId" type="string">
  The deleted conversationId.
</ResponseField>


<ResponseExample>
```json
{
"status": "success",
"message": `Conversation with ID abc1234aa deleted successfully.`,
"conversationId": abc1234aa,
}
```
</ResponseExample>

---

## Edit Customer Details

*Edit customers details in a specific conversation.*

### Headers  
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="conversationId" type="string" required>
  The unique identifier for the conversation whose customer details need to be edited.
</ParamField>

### Request Body

<ParamField body="name" type="string" optional> 
The new name of the customer. Provide this field only if you wish to update the name. 
</ParamField> 
<ParamField body="phone" type="string" optional> 
The new phone number of the customer in E.164 format (e.g., +1234567890). Provide this field only if you wish to update the phone number. 
<Note>
Make sure it is in E.164 format if you wish to change it.
</Note>
</ParamField> 
<ParamField body="email" type="string" optional> 
The new email address of the customer. Provide this field only if you wish to update the email. 
</ParamField>


### Response Fields

<ResponseField name="status" type="string">
  Indicates the status of the request. For successful requests, the value is "success".
</ResponseField>

<ResponseField name="conversationId" type="string">
  The unique identifier for the conversation where customer details were updated.
</ResponseField>

<ResponseField name="updatedCustomerDetails" type="object">
  An object containing the updated customer details.
  <Expandable title="Properties">
    <ResponseField name="name" type="string">
      The updated name of the customer.
    </ResponseField>
    <ResponseField name="email" type="string">
      The updated email address of the customer.
    </ResponseField>
    <ResponseField name="phone" type="string">
      The updated phone number of the customer in E.164 format.
    </ResponseField>
    <ResponseField name="_id" type="string">
      The unique identifier of the customer in the conversation.
    </ResponseField>
    <ResponseField name="createdAt" type="string">
      The timestamp when the customer was created in the conversation.
    </ResponseField>
    <ResponseField name="updatedAt" type="string">
      The timestamp when the customer details were last updated.
    </ResponseField>
  </Expandable>
</ResponseField>


<ResponseExample>
```json
{
    "status": "success",
    "conversationId": "123e3a141eccd665d3ba8abc",
    "updatedCustomerDetails": {
        "name": "Alice",
        "email": "alice@example.com",
        "phone": "+1234567890",
        "_id": "123c8e368824aa5f130b9xyz",
        "createdAt": "2025-01-01T12:00:00.000Z",
        "updatedAt": "2025-01-02T18:00:00.000Z"
    }
}
```
</ResponseExample>

---

## Generate Message

*Send an AI-generated message through either SMS or email to a specified recipient with optional metadata and dynamic configurations.*

### Headers  
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Request Body

<ParamField body="flowId" type="string" required>  
Unique identifier for the message flow sending the message. Ensure the Message Flow ID belongs to an active flow.  
</ParamField>  

<ParamField body="to" type="string" required>
Recipient's contact information. Use <b>E.164</b> format for SMS (e.g., `+1234567890`) and a valid email address format for Email (e.g., `user@example.com`).
<Note>
Ensure the contact format matches the <b>messageChannel</b> type: SMS for phone numbers and Email for email addresses. Using an incorrect format or type will result in an error.
</Note>
</ParamField>
  


<ParamField body="metadata" type="object" optional>  
  <Expandable title="properties">  
    <ParamField body="customerDetails" type="object" optional>  
      Details about the customer in key-value format. This field can contain the following:  
      <Expandable title="properties">  
        <ParamField body="name" type="string" optional>  
          The name of the customer. Example: `"Sam"`.
        </ParamField>
      </Expandable>  
    </ParamField>  
  </Expandable>  
</ParamField>  



<ParamField body="autopilot" type="boolean" required>  
Enable automatically sending the generated message to the intended recipient. If your flow has a `delay` enabled, the message will be sent after that delay. Defaults to `false`.  
</ParamField>  

<ParamField body="dynamic" type="object" optional>  
Dynamic inputs for AI-generated messages.  
</ParamField>  


### Response Fields

<ResponseField name="status" type="string">  
Indicates (`success`) if the request was successful.  
</ResponseField>  

<ResponseField name="conversation_id" type="string">  
Unique identifier for the newly created or fetched existing conversation.  
</ResponseField>  

<ResponseField name="message_id" type="string">  
Unique identifier for the newly created message within the conversation.  
</ResponseField>  

<ResponseField name="message" type="string">  
Content of the message sent. This will always be the corresponding message flow's `initiationMessage`.  
</ResponseField>  


<ResponseExample>  
```json  
{  
  "status": "success",  
  "conversation_id": "63e63b2a-8b6d-4ea4-ae84-abc123",  
  "message_id": "56f3459b-c23d-46a4-8a2d-bcd456",  
  "message": "Your appointment is confirmed for tomorrow at 3 PM."  
}  
```  
</ResponseExample>

---

## Get All Conversations

*Fetch all conversations associated with the authenticated user.*

### Headers  
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>


### Response Body

The response body will contain an array of the following fields:

<ResponseField name="_id" type="string">
  The unique identifier for the conversation.
</ResponseField>

<ResponseField name="userId" type="string">
  The unique identifier for the user associated with the conversation.
</ResponseField>

<ResponseField name="pathwayId" type="string">
  The unique identifier for the flows associated with the conversation.
</ResponseField>

<ResponseField name="agentId" type="string">
  The unique identifier for the agent handling the conversation.
</ResponseField>

<ResponseField name="customer" type="object">
  Customer details associated with the conversation.
  <Expandable title="properties">
    <ParamField body="name" type="string">
      The name of the customer.
    </ParamField>
    <ParamField body="email" type="string">
      The email address of the customer.
    </ParamField>
    <ParamField body="phone" type="string">
      The phone number of the customer.
    </ParamField>
  </Expandable>
</ResponseField>

<ResponseField name="messages" type="array">
  A list of messages within the conversation.
</ResponseField>

<ResponseField name="createdAt" type="string">
  The timestamp when the conversation was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  The timestamp when the conversation was last updated.
</ResponseField>

<ResponseExample>
```json
[
  {
    "_id": "675c8e368824aa5f130b94d6",
    "userId": "674e29976b6acbac106d2651",
    "pathwayId": "674e75bbe1456b11a194f091",
    "agentId": "674e7579e1456b11a194f08b",
    "customer": {
      "name": "Test Customer Name",
      "email": "customer@example.com",
      "phone": "+123456789"
    },
    "messages": [
      {
        "direction": "outbound",
        "sent": true,
        "message": "Thank you for your feedback!",
        "status": "approved",
        "_id": "675c8e368824aa5f130b94d3",
        "createdAt": "2024-12-01T08:45:00Z",
        "updatedAt": "2024-12-01T09:00:00Z"
      }
    ],
    "createdAt": "2024-12-01T08:45:00Z",
    "updatedAt": "2024-12-01T09:00:00Z"
  }
]
```
</ResponseExample>

---

## Get Conversation By ID

*Fetch the message history and details for a specific conversation.*

### Headers  
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters
<ParamField path="conversationId" type="string" required>
  The unique identifier of the conversation.
</ParamField>



### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the conversation.
</ResponseField>

<ResponseField name="userId" type="string">
  The unique identifier for the user associated with the conversation.
</ResponseField>

<ResponseField name="pathwayId" type="string">
  The unique identifier for the flow associated with the conversation.
</ResponseField>

<ResponseField name="agentId" type="string">
  The unique identifier for the agent handling the conversation.
</ResponseField>

<ResponseField name="customer" type="object">
  Customer details associated with the conversation.
  <ResponseField name="customer.name" type="string">
    The name of the customer.
  </ResponseField>
  <ResponseField name="customer.email" type="string">
    The email address of the customer.
  </ResponseField>
  <ResponseField name="customer.phone" type="string">
    The phone number of the customer.
  </ResponseField>
</ResponseField>

<ResponseField name="messages" type="array">
  An array of messages exchanged in the conversation.
  <Expandable title="Message Details">
    <ResponseField name="direction" type="string">
      The direction of the message (e.g., "outbound" or "inbound").
    </ResponseField>
    <ResponseField name="sent" type="boolean">
      Indicates whether the message was sent successfully.
    </ResponseField>
    <ResponseField name="message" type="string">
      The content of the message.
    </ResponseField>
    <ResponseField name="status" type="string">
      The status of the message (e.g., "approved", "received").
    </ResponseField>
    <ResponseField name="_id" type="string">
      The unique identifier for the message.
    </ResponseField>
    <ResponseField name="createdAt" type="string">
      Timestamp when the message was created.
    </ResponseField>
    <ResponseField name="updatedAt" type="string">
      Timestamp when the message was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the conversation was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the conversation was last updated.
</ResponseField>

### Response Example

<ResponseExample>
```json
{
  "_id": "112ec528bf7946a12ab0fs21",
  "userId": "60d9e3c2f42e4d03800e01a5",
  "pathwayId": "pw12345",
  "agentId": "ag67890",
  "customer": {
      "name": "Test Customer Name",
      "email": "customer@example.com",
      "phone": "+123456789"
    },
  "messages": [
      {
        "direction": "outbound",
        "sent": true,
        "message": "Thank you for your feedback!",
        "status": "approved",
        "_id": "675c8e368824aa5f130b94d3",
        "createdAt": "2024-12-01T08:45:00Z",
        "updatedAt": "2024-12-01T09:00:00Z"
      },
    {
        "direction": "inbound",
        "sent": true,
        "message": "No worries!",
        "status": "received",
        "_id": "675c8e368824aa5f130b94d3",
        "createdAt": "2024-12-01T08:55:00Z",
        "updatedAt": "2024-12-01T09:00:00Z"
      }
  ],
  "createdAt": "2024-12-01T08:45:00Z",
  "updatedAt": "2024-12-03T12:30:00Z"
}
```

</ResponseExample>

---

## Get Conversations By Flow ID

*Fetch the conversations for a specific flow.*

### Headers  
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters
<ParamField path="flowId" type="string" required>
  The unique identifier of the message flow.
</ParamField>


### Response Fields
The response body will contain an array of the following fields:

<ResponseField name="_id" type="string">
  The unique identifier for the conversation.
</ResponseField>

<ResponseField name="userId" type="string">
  The unique identifier for the user associated with the conversation.
</ResponseField>

<ResponseField name="pathwayId" type="string">
  The unique identifier for the flow associated with the conversation.
</ResponseField>

<ResponseField name="agentId" type="string">
  The unique identifier for the agent handling the conversation.
</ResponseField>

<ResponseField name="customer" type="object">
  Customer details associated with the conversation.
  <ResponseField name="customer.name" type="string">
    The name of the customer.
  </ResponseField>
  <ResponseField name="customer.email" type="string">
    The email address of the customer.
  </ResponseField>
  <ResponseField name="customer.phone" type="string">
    The phone number of the customer.
  </ResponseField>
</ResponseField>

<ResponseField name="messages" type="array">
  An array of messages exchanged in the conversation.
  <Expandable title="Message Details">
    <ResponseField name="direction" type="string">
      The direction of the message (e.g., "outbound" or "inbound").
    </ResponseField>
    <ResponseField name="sent" type="boolean">
      Indicates whether the message was sent successfully.
    </ResponseField>
    <ResponseField name="message" type="string">
      The content of the message.
    </ResponseField>
    <ResponseField name="status" type="string">
      The status of the message (e.g., "approved", "received").
    </ResponseField>
    <ResponseField name="_id" type="string">
      The unique identifier for the message.
    </ResponseField>
    <ResponseField name="createdAt" type="string">
      Timestamp when the message was created.
    </ResponseField>
    <ResponseField name="updatedAt" type="string">
      Timestamp when the message was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the conversation was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the conversation was last updated.
</ResponseField>

<ResponseExample>
```json
{
  "_id": "112ec528bf7946a12ab0fs21",
  "userId": "60d9e3c2f42e4d03800e01a5",
  "pathwayId": "pw12345",
  "agentId": "ag67890",
  "customer": {
      "name": "Test Customer Name",
      "email": "customer@example.com",
      "phone": "+123456789"
    },
  "messages": [
      {
        "direction": "outbound",
        "sent": true,
        "message": "Thank you for your feedback!",
        "status": "approved",
        "_id": "675c8e368824aa5f130b94d3",
        "createdAt": "2024-12-01T08:45:00Z",
        "updatedAt": "2024-12-01T09:00:00Z"
      },
    {
        "direction": "inbound",
        "sent": true,
        "message": "No worries!",
        "status": "received",
        "_id": "675c8e368824aa5f130b94d3",
        "createdAt": "2024-12-01T08:55:00Z",
        "updatedAt": "2024-12-01T09:00:00Z"
      }
  ],
  "createdAt": "2024-12-01T08:45:00Z",
  "updatedAt": "2024-12-03T12:30:00Z"
}
```

</ResponseExample>

---

## Handle Message Action

*Edit or reject a specific message within a conversation.*

### Headers  
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters
<ParamField path="conversationId" type="string" required>
  The unique identifier for the conversation containing the message.
</ParamField>

<ParamField path="messageId" type="string" required>
  The unique identifier for the message to be acted upon.
</ParamField>


### Request Body
<ParamField body="metadata" type="object" required>
  <Expandable title="properties">
    <ParamField body="action" type="string" required>
      The action to take: "Approve", "Edit", or "Reject".
      - **Approve**: Approves and sends the message.
      - **Edit**: Modifies the content of the message.
      - **Reject**: Rejects the message.
    </ParamField>
    <ParamField body="editedMessage" type="string" optional>
      The new content of the message, used only when the action is **Edit**.
    </ParamField>
  </Expandable>
</ParamField>

### Response Fields

<ResponseField name="status" type="string">
  The status of the action, indicating success or failure.
</ResponseField>

<ResponseField name="message" type="object">
  The updated or rejected message details.
  <Expandable title="properties">
    <ParamField body="_id" type="string">
      The unique identifier for the message.
    </ParamField>
    <ParamField body="message" type="string">
      The content of the message.
    </ParamField>
    <ParamField body="to" type="string">
      The recipient's phone number or email address.
    </ParamField>
    <ParamField body="sent" type="boolean">
      Whether the message has been sent.
    </ParamField>
    <ParamField body="status" type="string">
      The current status of the message, e.g., "approved", "rejected", etc.
    </ParamField>
    <ParamField body="timestamp" type="string">
      The timestamp of when the message was sent or updated.
    </ParamField>
  </Expandable>
</ResponseField>

<ResponseExample>
```json
{
  "status": "success",
  "message": {
    "_id": "64fbbc2e98312c4b82123456",
    "message": "Hello, how can I assist you?",
    "to": "+1234567890",
    "sent": true,
    "status": "approved",
    "timestamp": "2024-12-03T12:00:00Z"
  }
}
```
</ResponseExample>

---

## Add Flow to Folder

*Add a flow to a specific folder identified by its folderId.*

### Headers

<ParamField header="x-workspace-id" type="string" required>
  The unique identifier of the workspace being accessed.
</ParamField>

### Path Parameters

<ParamField path="folderId" type="string" required>
  The ID of the folder to which the flow will be added.
</ParamField>

### Request Body

<ParamField body="pathwayId" type="string" required>
  The ID of the flow to add to the folder.
</ParamField>

<ParamField body="pathwayType" type="string" required>
  The type of the flow, must be either "call" or "message".
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier of the folder.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the folder belongs.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the folder.
</ResponseField>

<ResponseField name="color" type="string">
  The color of the folder, represented as a hex code.
</ResponseField>

<ResponseField name="icon" type="string">
  The icon identifier for the folder.
</ResponseField>

<ResponseField name="flowType" type="string">
  The type of flow, either "call" or "message".
</ResponseField>

<ResponseField name="pathwayModel" type="string">
  The model type for flows, derived from `flowType`.
</ResponseField>

<ResponseField name="pathways" type="array">
  An array of flow IDs associated with the folder.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the folder was created (ISO 8601 format).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the folder was last updated (ISO 8601 format).
</ResponseField>

### Example Request

```json
{
  "pathwayId": "flow123",
  "pathwayType": "call"
}
```

<ResponseExample>
```json
{
  "_id": "folder123",
  "workspaceId": "workspace456",
  "name": "My Workflow Folder",
  "color": "#FF0000",
  "icon": "folder-icon",
  "flowType": "call",
  "pathwayModel": "Flow",
  "pathways": ["flow123"],
  "createdAt": "2023-10-15T09:30:00Z",
  "updatedAt": "2023-10-15T10:00:00Z"
}
```
</ResponseExample>

---

## Create Flow Folder

*Create a new flow folder in the specified workspace.*

### Headers

<ParamField header="x-workspace-id" type="string" required>
  The ID of the workspace to create the folder in.
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  The name of the folder (e.g., "My Workflow Folder").
</ParamField>

<ParamField body="color" type="string" required>
  The color of the folder, specified as one of the following color names with their corresponding hex codes: blue (#3B82F6), green (#10B981), teal (#14B8A6), purple (#8B5CF6), orange (#F97316), red (#EF4444).
</ParamField>

<ParamField body="icon" type="string" required>
  The icon identifier for the folder, specified as one of the following: folder, file, phone, headphone, voice, message.
</ParamField>

<ParamField body="flowType" type="string" required>
  The type of flow. Possible values: "call" or "message".
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the newly created folder.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the folder has been created.
</ResponseField>

<ResponseField name="name" type="string">
  The name given to the folder.
</ResponseField>

<ResponseField name="color" type="string">
  The color of the folder, as a hex code (e.g., "#3B82F6" for blue).
</ResponseField>

<ResponseField name="icon" type="string">
  The icon identifier for the folder (e.g., "folder").
</ResponseField>

<ResponseField name="flowType" type="string">
  The type of flow, either "call" or "message".
</ResponseField>

<ResponseField name="pathwayModel" type="string">
  The model type for flows, derived from `flowType`.
</ResponseField>

<ResponseField name="pathways" type="array">
  An array of flows associated with the folder (initially empty).
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the folder was created (ISO 8601 format).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the folder was last updated (ISO 8601 format).
</ResponseField>

### Example Request

```json
{
  "name": "My Workflow Folder",
  "color": "blue",
  "icon": "folder",
  "flowType": "call"
}
```

### Example Response (201 Created)

<ResponseExample>
```json
{
  "_id": "folder123",
  "workspaceId": "workspace456",
  "name": "My Workflow Folder",
  "color": "#3B82F6",
  "icon": "folder",
  "flowType": "call",
  "pathwayModel": "Flow",
  "pathways": [],
  "createdAt": "2023-10-15T09:30:00Z",
  "updatedAt": "2023-10-15T09:30:00Z"
}
```
</ResponseExample>

---

## Delete Folder

*Delete a specific folder identified by its folderId and remove its reference from associated flows.*

### Headers

<ParamField header="x-workspace-id" type="string" required>
  The unique identifier of the workspace being accessed.
</ParamField>

### Path Parameters

<ParamField path="folderId" type="string" required>
  The unique identifier of the folder to delete.
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier of the deleted folder.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the folder belonged.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the deleted folder.
</ResponseField>

<ResponseField name="color" type="string">
  The color of the deleted folder, represented as a hex code.
</ResponseField>

<ResponseField name="icon" type="string">
  The icon identifier for the deleted folder.
</ResponseField>

<ResponseField name="flowType" type="string">
  The type of flow, either "call" or "message".
</ResponseField>

<ResponseField name="pathwayModel" type="string">
  The model type for flows, derived from `flowType`.
</ResponseField>

<ResponseField name="pathways" type="array">
  An array of flow IDs that were associated with the deleted folder.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the folder was created (ISO 8601 format).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the folder was last updated (ISO 8601 format).
</ResponseField>

<ResponseExample>
```json
{
  "_id": "folder123",
  "workspaceId": "workspace456",
  "name": "My Workflow Folder",
  "color": "#FF0000",
  "icon": "folder-icon",
  "flowType": "call",
  "pathwayModel": "Flow",
  "pathways": ["flow123"],
  "createdAt": "2023-10-15T09:30:00Z",
  "updatedAt": "2023-10-15T10:00:00Z"
}
```
</ResponseExample>

---

## Get All Folders for Workspace

*Retrieve all folders associated with a specific workspace, identified by the workspace ID in the request header.*

### Headers

<ParamField header="x-workspace-id" type="string" required>
  The ID of the workspace whose folders are being requested.
</ParamField>

### Response Fields

An array of folder objects, each containing the following fields:

<ResponseField name="_id" type="string">
  The unique identifier of the folder.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the folder belongs.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the folder.
</ResponseField>

<ResponseField name="color" type="string">
  The color of the folder, represented as a hex code.
</ResponseField>

<ResponseField name="icon" type="string">
  The icon identifier for the folder.
</ResponseField>

<ResponseField name="flowType" type="string">
  The type of flow, either "call" or "message".
</ResponseField>

<ResponseField name="pathwayModel" type="string">
  The model type for flows, derived from `flowType`.
</ResponseField>

<ResponseField name="pathways" type="array">
  An array of flow IDs associated with the folder.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the folder was created (ISO 8601 format).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the folder was last updated (ISO 8601 format).
</ResponseField>

<ResponseExample>
```json
[
  {
    "_id": "folder123",
    "workspaceId": "workspace456",
    "name": "My Workflow Folder",
    "color": "#FF0000",
    "icon": "folder-icon",
    "flowType": "call",
    "pathwayModel": "Flow",
    "pathways": ["flow123"],
    "createdAt": "2023-10-15T09:30:00Z",
    "updatedAt": "2023-10-15T10:00:00Z"
  },
  {
    "_id": "folder124",
    "workspaceId": "workspace456",
    "name": "Message Folder",
    "color": "#00FF00",
    "icon": "message-icon",
    "flowType": "message",
    "pathwayModel": "MessageFlow",
    "pathways": [],
    "createdAt": "2023-10-14T08:00:00Z",
    "updatedAt": "2023-10-14T08:00:00Z"
  }
]
```
</ResponseExample>

---

## Get Folder Details with Flows

*Retrieve the details of a specific folder, including its associated flows, by its folderId.*

### Headers

<ParamField header="x-workspace-id" type="string" required>
  The unique identifier of the workspace being accessed.
</ParamField>

### Path Parameters

<ParamField path="folderId" type="string" required>
  The unique identifier of the folder whose details are being requested.
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier of the folder.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the folder belongs.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the folder.
</ResponseField>

<ResponseField name="color" type="string">
  The color of the folder, represented as a hex code.
</ResponseField>

<ResponseField name="icon" type="string">
  The icon identifier for the folder.
</ResponseField>

<ResponseField name="flowType" type="string">
  The type of flow, either "call" or "message".
</ResponseField>

<ResponseField name="pathwayModel" type="string">
  The model type for flows, derived from `flowType`.
</ResponseField>

<ResponseField name="pathways" type="array">
  An array of flow objects associated with the folder. Each flow object contains details such as its ID, name, and other relevant information.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the folder was created (ISO 8601 format).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the folder was last updated (ISO 8601 format).
</ResponseField>

<ResponseExample>
```json
{
  "_id": "folder123",
  "workspaceId": "workspace456",
  "name": "My Workflow Folder",
  "color": "#FF0000",
  "icon": "folder-icon",
  "flowType": "call",
  "pathwayModel": "Flow",
  "pathways": [
    {
      "_id": "flow123",
      "name": "Support Call Flow",
      "description": "Handles customer support calls",
      "createdAt": "2023-10-15T10:00:00Z",
      "updatedAt": "2023-10-15T10:00:00Z"
    }
  ],
  "createdAt": "2023-10-15T09:30:00Z",
  "updatedAt": "2023-10-15T10:00:00Z"
}
```
</ResponseExample>

---

## Remove Flow from Folder

*Remove a specific flow from a folder identified by its folderId and flowId.*

### Headers

<ParamField header="x-workspace-id" type="string" required>
  The unique identifier of the workspace being accessed.
</ParamField>

### Path Parameters

<ParamField path="folderId" type="string" required>
  The ID of the folder from which the flow will be removed.
</ParamField>

<ParamField path="pathwayId" type="string" required>
  The ID of the flow to remove from the folder.
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier of the folder.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the folder belongs.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the folder.
</ResponseField>

<ResponseField name="color" type="string">
  The color of the folder, represented as a hex code.
</ResponseField>

<ResponseField name="icon" type="string">
  The icon identifier for the folder.
</ResponseField>

<ResponseField name="flowType" type="string">
  The type of flow, either "call" or "message".
</ResponseField>

<ResponseField name="pathwayModel" type="string">
  The model type for flows, derived from `flowType`.
</ResponseField>

<ResponseField name="pathways" type="array">
  An updated array of flow IDs associated with the folder after removal.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the folder was created (ISO 8601 format).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the folder was last updated (ISO 8601 format).
</ResponseField>

<ResponseExample>
```json
{
  "_id": "folder123",
  "workspaceId": "workspace456",
  "name": "My Workflow Folder",
  "color": "#FF0000",
  "icon": "folder-icon",
  "flowType": "call",
  "pathwayModel": "Flow",
  "pathways": [],
  "createdAt": "2023-10-15T09:30:00Z",
  "updatedAt": "2023-10-15T11:00:00Z"
}
```
</ResponseExample>

---

## Update Folder

*Update the details of a specific folder identified by its folderId.*

### Headers

<ParamField header="x-workspace-id" type="string" required>
  The unique identifier of the workspace being accessed.
</ParamField>

### Path Parameters

<ParamField path="folderId" type="string" required>
  The unique identifier of the folder to update.
</ParamField>

### Request Body

<ParamField body="name" type="string">
  The updated name of the folder (e.g., "Updated Workflow Folder").
</ParamField>

<ParamField body="color" type="string" required>
  The color of the folder, specified as one of the following color names with their corresponding hex codes: blue (#3B82F6), green (#10B981), teal (#14B8A6), purple (#8B5CF6), orange (#F97316), red (#EF4444).
</ParamField>

<ParamField body="icon" type="string" required>
  The icon identifier for the folder, specified as one of the following: folder, file, phone, headphone, voice, message.
</ParamField>

<ParamField body="flowType" type="string">
  The updated type of flow, either "call" or "message".
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier of the folder.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the folder belongs.
</ResponseField>

<ResponseField name="name" type="string">
  The updated name of the folder.
</ResponseField>

<ResponseField name="color" type="string">
  The updated color of the folder, represented as a hex code.
</ResponseField>

<ResponseField name="icon" type="string">
  The updated icon identifier for the folder.
</ResponseField>

<ResponseField name="flowType" type="string">
  The updated type of flow, either "call" or "message".
</ResponseField>

<ResponseField name="pathwayModel" type="string">
  The model type for flows, derived from `flowType`.
</ResponseField>

<ResponseField name="pathways" type="array">
  An array of flow IDs associated with the folder.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the folder was created (ISO 8601 format).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the folder was last updated (ISO 8601 format).
</ResponseField>

### Example Request

```json
{
  "name": "Updated Workflow Folder",
  "color": "#00FF00",
  "icon": "new-folder-icon"
}
```

<ResponseExample>
```json
{
  "_id": "folder123",
  "workspaceId": "workspace456",
  "name": "Updated Workflow Folder",
  "color": "#00FF00",
  "icon": "new-folder-icon",
  "flowType": "call",
  "pathwayModel": "Flow",
  "pathways": ["flow123"],
  "createdAt": "2023-10-15T09:30:00Z",
  "updatedAt": "2023-10-16T12:00:00Z"
}
```
</ResponseExample>

---

## Add Text to Knowledge Base

*Add plain text content to an existing knowledge base.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique identifier of the knowledge base.
</ParamField>

## Request Body

<ParamField body="text" type="string" required>
The plain text content to add to the knowledge base.
</ParamField>

<ParamField body="name" type="string">
Optional name for the text entry.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the text was added successfully.
</ResponseField>

<ResponseExample>
```json
{
  "success": true
}
```
</ResponseExample>

---

## Create Knowledge Base

*Create a new knowledge base in your workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
Name of the knowledge base.
</ParamField>

<ParamField body="description" type="string">
Description of the knowledge base.
</ParamField>

## Response Fields

<ResponseField name="_id" type="string">
Unique identifier for the newly created knowledge base.
</ResponseField>

<ResponseField name="name" type="string">
Name of the knowledge base.
</ResponseField>

<ResponseField name="description" type="string">
Description of the knowledge base.
</ResponseField>

<ResponseField name="workspaceId" type="string">
Workspace ID associated with the knowledge base.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the knowledge base was created.
</ResponseField>

<ResponseExample>
```json
{
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "name": "Product Documentation",
  "description": "All product-related documentation and FAQs",
  "workspaceId": "664a1b2c3d4e5f6a7b8c9d0e",
  "files": [],
  "createdAt": "2024-06-01T09:00:00.000Z",
  "updatedAt": "2024-06-01T09:00:00.000Z"
}
```
</ResponseExample>

---

## Delete Knowledge Base

*Delete a knowledge base and all its associated files.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique identifier of the knowledge base to delete.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the deletion was successful.
</ResponseField>

<ResponseField name="message" type="string">
Confirmation message.
</ResponseField>

<ResponseExample>
```json
{
  "success": true,
  "message": "Knowledge base deleted successfully"
}
```
</ResponseExample>

---

## Get Knowledge Base Usage

*Retrieve usage information for a knowledge base, including which call flows are using it.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique identifier of the knowledge base.
</ParamField>

## Response Fields

<ResponseField name="pathways" type="array">
Array of call flows that are using this knowledge base.

<ResponseField name="_id" type="string">
Unique identifier of the call flow.
</ResponseField>

<ResponseField name="name" type="string">
Name of the call flow.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
{
  "pathways": [
    {
      "_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "name": "Customer Support Flow"
    },
    {
      "_id": "665a1b2c3d4e5f6a7b8c9d0f",
      "name": "Sales Inquiry Flow"
    }
  ]
}
```
</ResponseExample>

---

## Get Knowledge Base

*Retrieve a specific knowledge base by its ID.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique identifier of the knowledge base.
</ParamField>

## Response Fields

<ResponseField name="_id" type="string">
Unique identifier for the knowledge base.
</ResponseField>

<ResponseField name="name" type="string">
Name of the knowledge base.
</ResponseField>

<ResponseField name="description" type="string">
Description of the knowledge base.
</ResponseField>

<ResponseField name="workspaceId" type="string">
Workspace ID associated with the knowledge base.
</ResponseField>

<ResponseField name="files" type="array">
Array of files uploaded to the knowledge base.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the knowledge base was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
Timestamp when the knowledge base was last updated.
</ResponseField>

<ResponseExample>
```json
{
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "name": "Product Documentation",
  "description": "All product-related documentation and FAQs",
  "workspaceId": "664a1b2c3d4e5f6a7b8c9d0e",
  "files": [
    {
      "name": "product-guide.pdf",
      "size": 1048576,
      "type": "application/pdf",
      "uploadedAt": "2024-06-01T10:00:00.000Z"
    }
  ],
  "createdAt": "2024-06-01T09:00:00.000Z",
  "updatedAt": "2024-06-01T10:00:00.000Z"
}
```
</ResponseExample>

---

## List Knowledge Bases

*Retrieve all knowledge bases for a workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Response Fields

<ResponseField name="data" type="array">
Array of knowledge base objects.

<ResponseField name="_id" type="string">
Unique identifier for the knowledge base.
</ResponseField>

<ResponseField name="name" type="string">
Name of the knowledge base.
</ResponseField>

<ResponseField name="description" type="string">
Description of the knowledge base.
</ResponseField>

<ResponseField name="workspaceId" type="string">
Workspace ID associated with the knowledge base.
</ResponseField>

<ResponseField name="files" type="array">
Array of files uploaded to the knowledge base.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the knowledge base was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
Timestamp when the knowledge base was last updated.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
[
  {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "name": "Product Documentation",
    "description": "All product-related documentation and FAQs",
    "workspaceId": "664a1b2c3d4e5f6a7b8c9d0e",
    "files": [
      {
        "name": "product-guide.pdf",
        "size": 1048576,
        "type": "application/pdf",
        "uploadedAt": "2024-06-01T10:00:00.000Z"
      }
    ],
    "createdAt": "2024-06-01T09:00:00.000Z",
    "updatedAt": "2024-06-01T10:00:00.000Z"
  }
]
```
</ResponseExample>

---

## Update Knowledge Base

*Update the name or description of an existing knowledge base.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique identifier of the knowledge base to update.
</ParamField>

## Request Body

<ParamField body="name" type="string">
Updated name for the knowledge base.
</ParamField>

<ParamField body="description" type="string">
Updated description for the knowledge base.
</ParamField>

## Response Fields

<ResponseField name="_id" type="string">
Unique identifier for the knowledge base.
</ResponseField>

<ResponseField name="name" type="string">
Updated name of the knowledge base.
</ResponseField>

<ResponseField name="description" type="string">
Updated description of the knowledge base.
</ResponseField>

<ResponseExample>
```json
{
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "name": "Updated Product Docs",
  "description": "Updated documentation and FAQs",
  "workspaceId": "664a1b2c3d4e5f6a7b8c9d0e",
  "updatedAt": "2024-06-02T09:00:00.000Z"
}
```
</ResponseExample>

---

## Upload File to Knowledge Base

*Upload a file to an existing knowledge base. Supports PDF, TXT, DOCX, MD, CSV, and JSON files up to 50MB.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique identifier of the knowledge base to upload the file to.
</ParamField>

## Request Body

The request body should be sent as `multipart/form-data`.

<ParamField body="uploadedFile" type="file" required>
The file to upload. Supported formats: PDF, TXT, DOCX, MD, CSV, JSON. Maximum file size: 50MB.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the file was uploaded successfully.
</ResponseField>

<ResponseField name="file" type="object">
Details of the uploaded file.

<ResponseField name="name" type="string">
Name of the uploaded file.
</ResponseField>

<ResponseField name="size" type="number">
Size of the file in bytes.
</ResponseField>

<ResponseField name="type" type="string">
MIME type of the file.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
{
  "success": true,
  "file": {
    "name": "product-guide.pdf",
    "size": 1048576,
    "type": "application/pdf"
  }
}
```
</ResponseExample>

---

## Get Available Countries

*Retrieve a list of countries where phone numbers are available for purchase.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Response Fields

<ResponseField name="countries" type="array">
Array of available countries.

<ResponseField name="code" type="string">
Country code (e.g., "US", "CA", "AU", "GB").
</ResponseField>

<ResponseField name="name" type="string">
Full country name.
</ResponseField>

<ResponseField name="available" type="boolean">
Whether phone numbers are currently available in this country.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
{
  "countries": [
    { "code": "US", "name": "United States", "available": true },
    { "code": "CA", "name": "Canada", "available": true },
    { "code": "AU", "name": "Australia", "available": true },
    { "code": "GB", "name": "United Kingdom", "available": true }
  ]
}
```
</ResponseExample>

---

## Search Available Numbers

*Search for available phone numbers in a specific country.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Query Parameters

<ParamField query="country" type="string" required>
Country code to search for numbers (e.g., "US", "CA", "AU", "GB").
</ParamField>

<ParamField query="type" type="string" required>
Type of phone number. Options: "local", "tollFree", "mobile". Not required for AU.
</ParamField>

<ParamField query="contains" type="string">
Search for numbers containing specific digits or patterns.
</ParamField>

<ParamField query="limit" type="number">
Maximum number of results to return.
</ParamField>

## Response Fields

<ResponseField name="numbers" type="array">
Array of available phone numbers.

<ResponseField name="phoneNumber" type="string">
The phone number in E.164 format.
</ResponseField>

<ResponseField name="friendlyName" type="string">
A human-readable formatted version of the number.
</ResponseField>

<ResponseField name="locality" type="string">
City or locality associated with the number.
</ResponseField>

<ResponseField name="region" type="string">
State or region associated with the number.
</ResponseField>

</ResponseField>

<ResponseField name="filters" type="object">
Available filter options for the country.

<ResponseField name="supported" type="array">
List of supported filter types for the selected country.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
{
  "numbers": [
    {
      "phoneNumber": "+14155551234",
      "friendlyName": "(415) 555-1234",
      "locality": "San Francisco",
      "region": "CA"
    },
    {
      "phoneNumber": "+14155555678",
      "friendlyName": "(415) 555-5678",
      "locality": "San Francisco",
      "region": "CA"
    }
  ],
  "filters": {
    "supported": ["contains", "areaCode"]
  }
}
```
</ResponseExample>

---

## Get Phone Number Configuration

*Retrieve the call flow and message flow configuration for a phone number.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="phoneNumberId" type="string" required>
The unique identifier of the phone number.
</ParamField>

## Response Fields

<ResponseField name="phoneNumberId" type="string">
The phone number ID.
</ResponseField>

<ResponseField name="agentId" type="string">
The call agent assigned to this phone number.
</ResponseField>

<ResponseField name="flowType" type="string">
Type of flow assigned ("call" or "message").
</ResponseField>

<ResponseField name="direction" type="string">
Call direction configuration ("inbound", "outbound", "bidirectional").
</ResponseField>

<ResponseField name="status" type="string">
Configuration status.
</ResponseField>

<ResponseField name="recording" type="boolean">
Whether call recording is enabled.
</ResponseField>

<ResponseField name="officeHours" type="object">
Office hours configuration for the phone number.
</ResponseField>

<ResponseField name="transferCallerIdMode" type="string">
Caller ID mode for call transfers.
</ResponseField>

<ResponseField name="metadataTags" type="array">
Array of metadata tags assigned to this phone number.
</ResponseField>

<ResponseExample>
```json
{
  "phoneNumberId": "665a1b2c3d4e5f6a7b8c9d0e",
  "agentId": "665a1b2c3d4e5f6a7b8c9d0f",
  "flowType": "call",
  "direction": "bidirectional",
  "status": "active",
  "recording": true,
  "officeHours": {
    "enabled": false
  },
  "transferCallerIdMode": "agent",
  "metadataTags": ["sales", "priority"]
}
```
</ResponseExample>

---

## Get Phone Number Price

*Get the pricing for purchasing a phone number by country and type.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Query Parameters

<ParamField query="country" type="string" required>
Country code (e.g., "US", "CA", "AU", "GB").
</ParamField>

<ParamField query="type" type="string" required>
Type of phone number. Options: "local", "tollFree", "mobile".
</ParamField>

## Response Fields

<ResponseField name="country" type="string">
Country code.
</ResponseField>

<ResponseField name="type" type="string">
Phone number type.
</ResponseField>

<ResponseField name="price" type="number">
Monthly price for the phone number in USD.
</ResponseField>

<ResponseExample>
```json
{
  "country": "US",
  "type": "local",
  "price": 1.15
}
```
</ResponseExample>

---

## List Phone Numbers

*Retrieve all phone numbers associated with your workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Response Fields

<ResponseField name="phoneNumbers" type="array">
Array of phone number objects.

<ResponseField name="_id" type="string">
Unique identifier for the phone number record.
</ResponseField>

<ResponseField name="phoneNumber" type="string">
The phone number in E.164 format (e.g., +14155551234).
</ResponseField>

<ResponseField name="provider" type="string">
The telephony provider (e.g., "twilio", "sip").
</ResponseField>

<ResponseField name="country" type="string">
Country code of the phone number (e.g., "US", "AU").
</ResponseField>

<ResponseField name="type" type="string">
Type of phone number (e.g., "local", "tollFree", "mobile").
</ResponseField>

<ResponseField name="status" type="string">
Current status of the phone number.
</ResponseField>

<ResponseField name="workspaceId" type="string">
Workspace ID associated with the phone number.
</ResponseField>

<ResponseField name="label" type="string">
Optional label for the phone number.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
{
  "phoneNumbers": [
    {
      "_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "phoneNumber": "+14155551234",
      "provider": "twilio",
      "country": "US",
      "type": "local",
      "status": "active",
      "workspaceId": "664a1b2c3d4e5f6a7b8c9d0e",
      "label": "Sales Line"
    }
  ]
}
```
</ResponseExample>

---

## Purchase Phone Number

*Purchase a phone number for your workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Request Body

<ParamField body="country" type="string" required>
Country code for the phone number (e.g., "US", "CA").
</ParamField>

<ParamField body="type" type="string" required>
Type of phone number. Options: "local", "tollFree", "mobile".
</ParamField>

<ParamField body="phoneNumber" type="string" required>
The specific phone number to purchase in E.164 format.
</ParamField>

<ParamField body="addressSid" type="string">
Address SID for regulatory compliance (required for some countries).
</ParamField>

<ParamField body="coupon" type="string">
Coupon code for a discount.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the purchase was successful.
</ResponseField>

<ResponseField name="phoneNumber" type="object">
The purchased phone number details.

<ResponseField name="_id" type="string">
Unique identifier for the phone number record.
</ResponseField>

<ResponseField name="phoneNumber" type="string">
The purchased phone number in E.164 format.
</ResponseField>

<ResponseField name="country" type="string">
Country code.
</ResponseField>

<ResponseField name="type" type="string">
Phone number type.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
{
  "success": true,
  "phoneNumber": {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "phoneNumber": "+14155551234",
    "country": "US",
    "type": "local",
    "status": "active",
    "workspaceId": "664a1b2c3d4e5f6a7b8c9d0e"
  }
}
```
</ResponseExample>

---

## Release Phone Number

*Release (cancel) a phone number from your workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Request Body

<ParamField body="phoneNumberId" type="string" required>
The unique identifier of the phone number to release.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the release was successful.
</ResponseField>

<ResponseField name="message" type="string">
Confirmation message.
</ResponseField>

<ResponseExample>
```json
{
  "success": true,
  "message": "Phone number released successfully"
}
```
</ResponseExample>

---

## Update Phone Number Configuration

*Update the call flow configuration for a phone number, including agent assignment, recording, and office hours.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="phoneNumberId" type="string" required>
The unique identifier of the phone number.
</ParamField>

## Request Body

<ParamField body="agentId" type="string">
The call agent ID to assign to this phone number.
</ParamField>

<ParamField body="maxCallDuration" type="number">
Maximum call duration in seconds.
</ParamField>

<ParamField body="recordingEnabled" type="boolean">
Whether to enable call recording.
</ParamField>

<ParamField body="officeHours" type="object">
Office hours configuration.

<Expandable title="properties">

<ParamField body="enabled" type="boolean">
Whether office hours are enabled.
</ParamField>

<ParamField body="timezone" type="string">
Timezone for office hours (e.g., "America/New_York").
</ParamField>

<ParamField body="schedule" type="object">
Weekly schedule with day-specific hours.
</ParamField>

</Expandable>
</ParamField>

<ParamField body="transferCallerIdMode" type="string">
Caller ID mode for transfers. Options: "agent", "customer".
</ParamField>

<ParamField body="metadataTags" type="array">
Array of metadata tag strings to assign.
</ParamField>

<ParamField body="label" type="string">
A label for the phone number.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the update was successful.
</ResponseField>

<ResponseExample>
```json
{
  "success": true
}
```
</ResponseExample>

---

## Create Role

*Create a new role with specific permissions for your workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
Name of the role (e.g., "Agent Manager", "Viewer").
</ParamField>

<ParamField body="description" type="string">
Description of the role and its intended use.
</ParamField>

<ParamField body="permissions" type="array of strings" required>
Array of permission ID strings to assign to this role. **Always required — pass an empty array `[]` if no permissions are needed.** Each item must be a plain string (e.g., `"agent_view"`), not an object. Use the [List Permissions](/v1/api-reference/endpoints/roles/list-permissions) endpoint to retrieve available permission IDs.
</ParamField>

<ParamField body="userIds" type="array">
Array of user IDs to assign this role to.
</ParamField>

## Response Fields

<ResponseField name="_id" type="string">
Unique identifier for the created role.
</ResponseField>

<ResponseField name="name" type="string">
Name of the role.
</ResponseField>

<ResponseField name="description" type="string">
Description of the role.
</ResponseField>

<ResponseField name="permissions" type="array">
Array of permission objects assigned to the role.
</ResponseField>

<ResponseField name="workspaceId" type="string">
Workspace ID associated with the role.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the role was created.
</ResponseField>

<RequestExample>
```json With permissions
{
  "name": "Manager",
  "description": "Full access to agents and call history",
  "permissions": [
    "agent_view",
    "agent_create",
    "agent_edit",
    "call_history_view"
  ]
}
```

```json Minimal (no permissions)
{
  "name": "Viewer",
  "description": "Read-only role",
  "permissions": []
}
```
</RequestExample>

<ResponseExample>
```json
{
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "name": "Manager",
  "description": "Full access to agents and call history",
  "permissions": [
    { "key": "agent_view", "category": "agents" },
    { "key": "agent_create", "category": "agents" },
    { "key": "agent_edit", "category": "agents" },
    { "key": "call_history_view", "category": "calls" }
  ],
  "workspaceId": "664a1b2c3d4e5f6a7b8c9d0e",
  "createdAt": "2024-06-01T09:00:00.000Z"
}
```
</ResponseExample>

---

## Delete Role

*Delete a role from your workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="roleId" type="string" required>
The unique identifier of the role to delete.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the deletion was successful.
</ResponseField>

<ResponseExample>
```json
{
  "success": true
}
```
</ResponseExample>

---

## Get Role

*Retrieve a specific role by its ID.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="roleId" type="string" required>
The unique identifier of the role.
</ParamField>

## Response Fields

<ResponseField name="_id" type="string">
Unique identifier for the role.
</ResponseField>

<ResponseField name="name" type="string">
Name of the role.
</ResponseField>

<ResponseField name="description" type="string">
Description of the role.
</ResponseField>

<ResponseField name="permissions" type="array">
Array of permission objects assigned to the role.
</ResponseField>

<ResponseField name="userIds" type="array">
Array of user IDs assigned to this role.
</ResponseField>

<ResponseExample>
```json
{
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "name": "Agent Manager",
  "description": "Can manage agents and view call history",
  "permissions": [
    { "key": "agent_view", "category": "agents" },
    { "key": "agent_create", "category": "agents" },
    { "key": "agent_edit", "category": "agents" }
  ],
  "userIds": ["user_001"]
}
```
</ResponseExample>

---

## List Available Permissions

*Retrieve all available permissions that can be assigned to roles.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Response Fields

<ResponseField name="permissions" type="array">
Array of permission objects grouped by category.

<ResponseField name="key" type="string">
Unique permission key (e.g., "agent_view", "call_history_export").
</ResponseField>

<ResponseField name="name" type="string">
Human-readable permission name.
</ResponseField>

<ResponseField name="description" type="string">
Description of what the permission allows.
</ResponseField>

<ResponseField name="category" type="string">
Permission category (e.g., "agents", "calls", "workspace", "flows").
</ResponseField>

</ResponseField>

<ResponseExample>
```json
[
  {
    "key": "agent_view",
    "name": "View Agents",
    "description": "View agent configurations and details",
    "category": "agents"
  },
  {
    "key": "agent_create",
    "name": "Create Agents",
    "description": "Create new agents",
    "category": "agents"
  },
  {
    "key": "call_history_view",
    "name": "View Call History",
    "description": "View call history records and transcripts",
    "category": "calls"
  }
]
```
</ResponseExample>

---

## List Roles

*Retrieve all roles defined in your workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Response Fields

<ResponseField name="roles" type="array">
Array of role objects.

<ResponseField name="_id" type="string">
Unique identifier for the role.
</ResponseField>

<ResponseField name="name" type="string">
Name of the role.
</ResponseField>

<ResponseField name="description" type="string">
Description of the role.
</ResponseField>

<ResponseField name="permissions" type="array">
Array of permission objects.
</ResponseField>

<ResponseField name="userIds" type="array">
Array of user IDs assigned to this role.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
[
  {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "name": "Admin",
    "description": "Full access to all workspace features",
    "permissions": [
      { "key": "agent_view", "category": "agents" },
      { "key": "agent_create", "category": "agents" }
    ],
    "userIds": ["user_001", "user_002"]
  },
  {
    "_id": "665a1b2c3d4e5f6a7b8c9d0f",
    "name": "Viewer",
    "description": "Read-only access",
    "permissions": [
      { "key": "agent_view", "category": "agents" },
      { "key": "call_history_view", "category": "calls" }
    ],
    "userIds": ["user_003"]
  }
]
```
</ResponseExample>

---

## Update Role

*Update an existing role's name, description, or permissions.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="roleId" type="string" required>
The unique identifier of the role to update.
</ParamField>

## Request Body

<ParamField body="name" type="string">
Updated name for the role.
</ParamField>

<ParamField body="description" type="string">
Updated description for the role.
</ParamField>

<ParamField body="permissions" type="array of strings">
Updated array of permission ID strings. Each item must be a string (e.g., `"agent_view"`). Use the [List Permissions](/v1/api-reference/endpoints/roles/list-permissions) endpoint to retrieve available permission IDs.
</ParamField>

<ParamField body="userIds" type="array">
Updated array of user IDs to assign.
</ParamField>

## Response Fields

<ResponseField name="_id" type="string">
Unique identifier for the role.
</ResponseField>

<ResponseField name="name" type="string">
Updated name of the role.
</ResponseField>

<ResponseField name="description" type="string">
Updated description of the role.
</ResponseField>

<ResponseField name="permissions" type="array">
Updated permissions array.
</ResponseField>

<RequestExample>
```json
{
  "name": "Senior Manager",
  "description": "Full access to everything including billing and settings",
  "permissions": [
    "agent_view",
    "agent_create",
    "agent_edit",
    "agent_delete",
    "call_history_view"
  ]
}
```
</RequestExample>

<ResponseExample>
```json
{
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "name": "Senior Manager",
  "description": "Full access to everything including billing and settings",
  "permissions": [
    { "key": "agent_view", "category": "agents" },
    { "key": "agent_create", "category": "agents" },
    { "key": "agent_edit", "category": "agents" },
    { "key": "agent_delete", "category": "agents" },
    { "key": "call_history_view", "category": "calls" }
  ]
}
```
</ResponseExample>

---

## Assign Phone Number to Agent

*Assign a specific phone number to an agent's call flow, configure recording options, office hours, metadata, and automatically update SIP trunks.*

### Path Parameters

<ParamField path="agentId" type="string" required>
  The ID of the agent whose call flow will be bound to the phone number.
</ParamField>

<ParamField path="phoneNumberId" type="string" required>
  The ID of the phone number to bind.
</ParamField>

### Headers

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API. Required to scope the binding operation.
</ParamField>

### Request Body

<ParamField body="recordCalls" type="boolean" optional>
  Whether calls should be recorded. When enabled, updates Twilio trunk recording settings (`record-from-ringing`).  
  Default: `false`.
</ParamField>

<ParamField body="recordingPublic" type="boolean" optional>
  Whether recordings are publicly accessible.  
  Default: `false`.
</ParamField>

<ParamField body="officeHours" type="object" optional>
  Custom office hours configuration for the phone number (stored with the binding).  
  Example: `{ "monday": ["09:00-17:00"], "tuesday": [] }`.
</ParamField>

<ParamField body="metadataTags" type="object" optional>
  Arbitrary metadata key/value tags to store with the phone number.  
  Example: `{ "department": "sales", "priority": "high" }`.
</ParamField>

### Response Fields

<ResponseField name="agent" type="object">
  The updated agent object, including its bound phone number IDs.
</ResponseField>

<ResponseField name="phoneNumber" type="object">
  The updated phone number object after binding and SIP trunk configuration.
</ResponseField>

<ResponseField name="pathwayId" type="string">
  The ID of the call flow associated with this assignment.
</ResponseField>

<ResponseField name="direction" type="string">
  The direction of the call flow (`inbound`, `outbound`, or `bidirectional`).
</ResponseField>

<ResponseExample>
```
{
  "agent": {
    "_id": "64f9b12a",
    "status": "ready",
    "phoneNumberIds": ["750cd920"]
  },
  "phoneNumber": {
    "_id": "750cd920",
    "agentId": "64f9b12a",
    "recordingEnabled": true,
    "recordingPublic": false,
    "officeHours": {
      "monday": ["09:00-17:00"],
      "tuesday": []
    },
    "metadataTags": {
      "department": "support",
      "priority": "high"
    }
  },
  "pathwayId": "pwy_abc123",
  "direction": "bidirectional"
}
```
</ResponseExample>

---

## Bring Your Own Number

*Register your own external phone number with Twilio to use within your workspace.*

### Headers

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Request Body

<ParamField body="phoneNumber" type="string" required>
  The external phone number to register, in E.164 format (e.g., `+11234567890`).
</ParamField>

<ParamField body="provider" type="string" required>
  The provider for the phone number. Currently, only `"twilio"` is supported.
</ParamField>

<ParamField body="credentials" type="object" required>
  The credentials required for the provider.
  <Expandable title="Credentials Details">
    <ParamField body="accountSid" type="string" required>
      The Account SID from Twilio.
    </ParamField>
    <ParamField body="authToken" type="string" required>
      The Auth Token from Twilio.
    </ParamField>
  </Expandable>
</ParamField>

### Response Fields

<ResponseField name="status" type="string">
  The status of the request, indicating success or failure.
</ResponseField>

<ResponseField name="message" type="string">
  A message providing feedback about the registration process.
</ResponseField>

### Example Response

<ResponseExample>
```json
{
  "status": "success",
  "message": "Phone number registered successfully"
}
```
</ResponseExample>

---

## Unassign Phone Number from Agent

*Unassign a phone number from an agent's call flow. This removes the assignment and automatically cleans up associated SIP trunking.*

### Path Parameters

<ParamField path="agentId" type="string" required>
  The ID of the agent whose phone number will be released.
</ParamField>

<ParamField path="phoneNumberId" type="string" required>
  The ID of the phone number to release from the agent.
</ParamField>

### Headers

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API. Required to scope the release operation.
</ParamField>

### Request Body

<ParamField body="confirmation" type="boolean" optional>
  Are you sure you want to unbind this?
</ParamField>

### Response Fields

<ResponseField name="agent" type="object">
  The updated agent object after the phone number has been released.
</ResponseField>

### Request Body

No request body is required for this endpoint.

<ResponseExample>
```json
{
  "status": "success",
  "message": "Call flow released from phone number successfully"
}
```
</ResponseExample>

---

## Get Recording

*Stream the audio recording for a specific call. Returns the recording file with appropriate audio headers.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
The unique identifier of the workspace being accessed.
</ParamField>

## Path Parameters

<ParamField path="callHistoryId" type="string" required>
The call history ID to retrieve the recording for.
</ParamField>

## Response

The response streams the audio file directly with the following headers:

- `Content-Type`: `audio/mp3` or `video/mp4` depending on the recording format
- `Content-Disposition`: `inline; filename="recording.mp3"`
- `Cache-Control`: `private, max-age=3600`

The audio file is streamed directly and can be played in a browser or downloaded.

---

## Start Recording

*Start recording an active call.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Request Body

<ParamField body="pathwayId" type="string" required>
The call flow pathway ID associated with the call.
</ParamField>

<ParamField body="roomName" type="string" required>
The LiveKit room name of the active call to start recording.
</ParamField>

## Response Fields

<ResponseField name="message" type="string">
Confirmation message.
</ResponseField>

<ResponseField name="result" type="object">
Recording result details from LiveKit.
</ResponseField>

<ResponseExample>
```json
{
  "message": "Recording started successfully",
  "result": {
    "egressId": "EG_abc123"
  }
}
```
</ResponseExample>

---

## Clone Voice

*Clone a voice from an audio file to create a custom voice with a unique voice embedding.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Request Body

The request body should be sent as `multipart/form-data`.

<ParamField body="file" type="file" required>
Audio file to clone the voice from. Maximum file size: 50MB.
</ParamField>

<ParamField body="name" type="string">
Name for the cloned voice.
</ParamField>

<ParamField body="description" type="string">
Description of the cloned voice.
</ParamField>

<ParamField body="language" type="string">
Language code for the voice (e.g., "en").
</ParamField>

## Response Fields

<ResponseField name="embedding" type="object">
The voice embedding data generated from the audio file.
</ResponseField>

<ResponseField name="voice" type="object">
The created custom voice object (if name was provided).

<ResponseField name="_id" type="string">
Unique identifier for the custom voice.
</ResponseField>

<ResponseField name="name" type="string">
Name of the custom voice.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
{
  "embedding": {
    "data": "...",
    "format": "float32"
  },
  "voice": {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "name": "My Custom Voice",
    "description": "Cloned from recording",
    "language": "en",
    "workspaceId": "664a1b2c3d4e5f6a7b8c9d0e"
  }
}
```
</ResponseExample>

---

## Create Custom Voice

*Create a custom voice using a voice embedding.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
Name for the custom voice.
</ParamField>

<ParamField body="description" type="string">
Description of the custom voice.
</ParamField>

<ParamField body="embedding" type="object" required>
Voice embedding object generated from voice cloning.
</ParamField>

<ParamField body="language" type="string">
Language code for the voice (e.g., "en").
</ParamField>

## Response Fields

<ResponseField name="_id" type="string">
Unique identifier for the custom voice.
</ResponseField>

<ResponseField name="name" type="string">
Name of the custom voice.
</ResponseField>

<ResponseField name="description" type="string">
Description of the custom voice.
</ResponseField>

<ResponseField name="workspaceId" type="string">
Workspace that owns the custom voice.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the voice was created.
</ResponseField>

<ResponseExample>
```json
{
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "name": "Custom Sales Voice",
  "description": "Professional sales voice",
  "language": "en",
  "workspaceId": "664a1b2c3d4e5f6a7b8c9d0e",
  "createdAt": "2024-06-01T09:00:00.000Z"
}
```
</ResponseExample>

---

## Delete Voice

*Delete a custom voice from your workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique identifier of the voice to delete.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the deletion was successful.
</ResponseField>

<ResponseExample>
```json
{
  "success": true
}
```
</ResponseExample>

---

## Get Voice

*Retrieve a specific voice by its ID.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique identifier of the voice.
</ParamField>

## Response Fields

<ResponseField name="_id" type="string">
Unique identifier for the voice.
</ResponseField>

<ResponseField name="name" type="string">
Display name of the voice.
</ResponseField>

<ResponseField name="voiceId" type="string">
Voice ID used in TTS configuration.
</ResponseField>

<ResponseField name="provider" type="string">
TTS provider for this voice.
</ResponseField>

<ResponseField name="gender" type="string">
Gender of the voice.
</ResponseField>

<ResponseField name="accent" type="string">
Accent of the voice.
</ResponseField>

<ResponseField name="description" type="string">
Description of the voice characteristics.
</ResponseField>

<ResponseExample>
```json
{
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "name": "Wildflower",
  "voiceId": "mistv2_Wildflower",
  "provider": "rime",
  "gender": "female",
  "accent": "american",
  "description": "Alt Female, Smart"
}
```
</ResponseExample>

---

## List Custom Voices

*Retrieve all custom voices created in your workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Response Fields

<ResponseField name="voices" type="array">
Array of custom voice objects.

<ResponseField name="_id" type="string">
Unique identifier for the custom voice.
</ResponseField>

<ResponseField name="name" type="string">
Name of the custom voice.
</ResponseField>

<ResponseField name="description" type="string">
Description of the custom voice.
</ResponseField>

<ResponseField name="language" type="string">
Language code for the voice.
</ResponseField>

<ResponseField name="workspaceId" type="string">
Workspace that owns the custom voice.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the voice was created.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
[
  {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "name": "Custom Sales Voice",
    "description": "Friendly sales representative voice",
    "language": "en",
    "workspaceId": "664a1b2c3d4e5f6a7b8c9d0e",
    "createdAt": "2024-06-01T09:00:00.000Z"
  }
]
```
</ResponseExample>

---

## Search Voices

*Search available voices by name, category, gender, accent, age, use case, or provider.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Query Parameters

<ParamField query="name" type="string">
Search voices by name.
</ParamField>

<ParamField query="category" type="string">
Filter by voice category.
</ParamField>

<ParamField query="gender" type="string">
Filter by gender (e.g., "male", "female").
</ParamField>

<ParamField query="accent" type="string">
Filter by accent (e.g., "american", "british", "australian").
</ParamField>

<ParamField query="age" type="string">
Filter by age range (e.g., "young", "middle_aged", "old").
</ParamField>

<ParamField query="useCase" type="string">
Filter by use case (e.g., "conversational", "narration").
</ParamField>

<ParamField query="provider" type="string">
Filter by provider (e.g., "rime", "elevenlabs", "hume", "cartesia").
</ParamField>

## Response Fields

<ResponseField name="voices" type="array">
Array of matching voice objects.

<ResponseField name="_id" type="string">
Unique identifier for the voice.
</ResponseField>

<ResponseField name="name" type="string">
Display name of the voice.
</ResponseField>

<ResponseField name="voiceId" type="string">
Voice ID used in TTS configuration.
</ResponseField>

<ResponseField name="provider" type="string">
TTS provider for this voice.
</ResponseField>

<ResponseField name="gender" type="string">
Gender of the voice.
</ResponseField>

<ResponseField name="accent" type="string">
Accent of the voice.
</ResponseField>

<ResponseField name="description" type="string">
Description of the voice characteristics.
</ResponseField>

<ResponseField name="previewUrl" type="string">
URL to a voice preview audio sample.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
[
  {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "name": "Wildflower",
    "voiceId": "mistv2_Wildflower",
    "provider": "rime",
    "gender": "female",
    "accent": "american",
    "description": "Alt Female, Smart",
    "previewUrl": "https://example.com/preview.mp3"
  },
  {
    "_id": "665a1b2c3d4e5f6a7b8c9d0f",
    "name": "Brook",
    "voiceId": "mistv2_Brook",
    "provider": "rime",
    "gender": "male",
    "accent": "american",
    "description": "Male, Friendly"
  }
]
```
</ResponseExample>

---

## Create Workspace

*Create a new workspace with the authenticated user as the owner.*

### Headers

<ParamField header="x-workspace-id" type="string" required>
  The unique identifier of any workspace you are a member of. Required by the auth middleware when using API key authentication — this does not need to match any specific workspace; the new workspace will still be created for the authenticated user.
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  The name of the workspace (e.g., "Marketing Team Workspace").
</ParamField>

<ParamField body="initials" type="string" required>
  Initials representing the workspace (e.g., "MT").
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the newly created workspace.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the workspace.
</ResponseField>


<ResponseField name="initials" type="string">
  The initials assigned to the workspace.
</ResponseField>


<ResponseField name="teamMembers" type="array">
  List of team members associated with the workspace, starting with the owner.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the workspace was created (ISO 8601 format).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the workspace was last updated (ISO 8601 format).
</ResponseField>

---

## Delete Workspace

*Delete an existing workspace. Only the owner of the workspace can delete it. Master workspaces and the user's only remaining workspace cannot be deleted.*

### Path Parameters

<ParamField path="workspaceId" type="string" required>
  The unique identifier of the workspace to delete.
</ParamField>

### Headers

<ParamField header="x-workspace-id" type="string" required>
  The workspace ID being accessed (should match the path parameter).
</ParamField>

### Description

This endpoint allows the authenticated owner of a workspace to delete it, subject to the following restrictions:

- The workspace **cannot be the master workspace**.
- The workspace **cannot be the user's only remaining workspace**.
- The requester **must be the owner** of the workspace (team members are not authorized).

If the workspace contains external members, their access is revoked before deletion. The associated workspace wallet is also deleted as part of this operation.

### Response Fields

<ResponseField name="success" type="boolean">
  Indicates whether the workspace was successfully deleted.
</ResponseField>

---

## Get Pending Invitations

*Retrieve a list of pending workspace invitations for the authenticated user.*

### Headers
<ParamField header="x-workspace-id" type="string" optional>
  The workspace ID related to the invitation context. *(Currently optional and not enforced in the query.)*
</ParamField>

### Description

This endpoint returns all **pending workspace invitations** where the authenticated user's email matches the invitation's recipient email.

The response includes:
- Details about the invitation (role, type, token, expiration).
- Information about the inviting user (name, email, picture).
- Workspace details including name, initials, and white-label settings.

If the email is not present in the authenticated user payload, it is fetched from the database using the user ID.

### Response Fields

<ResponseField name="success" type="boolean">
  Indicates whether the request was successful.
</ResponseField>

<ResponseField name="invitations" type="array">
  List of pending invitations for the authenticated user.
</ResponseField>

---

## Get Workspace by ID

*Retrieve detailed information about a specific workspace where the authenticated user is either the owner or a team member.*

### Headers
<ParamField header="x-workspace-id" type="string" required>
The unique identifier of the workspace being accessed (should match the path parameter `workspaceId`).
</ParamField>

### Path Parameters

<ParamField path="workspaceId" type="string" required>
  The unique identifier of the workspace to retrieve.
</ParamField>

### Description

This endpoint returns the details of a specific workspace if the authenticated user is authorized to access it. The user must be either:
- The **owner** of the workspace, or
- A **team member** of the workspace (internal or external).

If the workspace is not found or the user lacks permission, a `404 Not Found` is returned.

### Response Fields

<ResponseField name="_id" type="string">
  Unique identifier of the workspace.
</ResponseField>

<ResponseField name="name" type="string">
  Name of the workspace.
</ResponseField>

<ResponseField name="initials" type="string">
  Initials of the workspace.
</ResponseField>


<ResponseField name="teamMembers" type="array">
  List of team members associated with the workspace.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when the workspace was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp when the workspace was last updated.
</ResponseField>

---

## List User Workspaces

*Retrieve all workspaces associated with the authenticated user. If the user does not exist, a new user and default workspace may be automatically created.*

### Headers

<ParamField header="x-workspace-id" type="string" required>
  The unique identifier of any workspace you are a member of. Required by the auth middleware when using API key authentication — this endpoint still returns all workspaces the authenticated user has access to, regardless of which workspace ID is provided here.
</ParamField>

### Description

This endpoint returns a list of workspaces where the authenticated user is either:
- The **owner** of the workspace,
- An **internal team member**, or
- An **external team member**.

If the user is signing in for the first time, the system will:
1. Check for any pending invitations and join the user to an existing workspace if one exists.
2. If no invitation exists, create a default workspace for the user.

The response includes both direct workspaces and external workspaces, sorted in the following order:
1. Owned workspaces,
2. Team memberships,
3. Guest workspaces.


### Response Fields

<ResponseField name="_id" type="string">
  Unique identifier of the workspace.
</ResponseField>

<ResponseField name="name" type="string">
  Name of the workspace.
</ResponseField>

<ResponseField name="initials" type="string">
  Initials of the workspace.
</ResponseField>


<ResponseField name="teamMembers" type="array">
  List of team members associated with the workspace, including their roles and optional external workspace details.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the workspace was created (ISO 8601 format).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the workspace was last updated (ISO 8601 format).
</ResponseField>

---

## Invite Team Member

*Invite a new team member to join a workspace. Only workspace owners can send invitations.*

### Path Parameters

<ParamField path="workspaceId" type="string" required>
  The unique identifier of the workspace where the invitation is being sent.
</ParamField>

### Headers

<ParamField header="x-workspace-id" type="string" required>
  The unique identifier of the workspace being accessed (should match the path parameter `:workspaceId`).
</ParamField>


### Request Body

<ParamField body="email" type="string" required>
  The email address of the person to invite.
</ParamField>

<ParamField body="role" type="string" required>
  The role to assign to the invited user ("admin", "editor", "viewer").
</ParamField>

### Description

This endpoint allows a **workspace owner** to invite a new team member to their workspace by email.

- The system checks for any existing pending invitation for the same email to prevent duplicates.
- A new **invitation record** is created and stored with a 7-day expiration.
- An invitation email is sent to the invitee with a secure link to accept the invitation.

If the workspace is configured in **agency mode** with white-label settings, the invitation email will be sent using the workspace's verified custom email (if available).

### Invitation Email Behavior

- The email contains the inviter’s email, the workspace name, and a secure invitation acceptance link.
- If the workspace has a **white-label custom domain**, the invitation link will use that domain.
- If no custom domain is available, the link will use the default frontend URL.

The invitation expires automatically after **7 days** if not accepted.

### Response Fields

<ResponseField name="success" type="boolean">
  Indicates whether the invitation was successfully sent.
</ResponseField>

<ResponseField name="message" type="string">
  A message confirming the outcome of the invitation process.
</ResponseField>

---

## Update Workspace Name

*Update the name of an existing workspace. Only the owner of the workspace is authorized to perform this action.*

### Path Parameters

<ParamField path="workspaceId" type="string" required>
  The unique identifier of the workspace to update.
</ParamField>

### Headers

<ParamField header="x-workspace-id" type="string" required>
  The workspace ID (should match the `workspaceId` path parameter).
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  The new name for the workspace.
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier of the workspace.
</ResponseField>

<ResponseField name="name" type="string">
  The updated name of the workspace.
</ResponseField>


<ResponseField name="initials" type="string">
  The initials assigned to the workspace.
</ResponseField>


<ResponseField name="teamMembers" type="array">
  List of team members associated with the workspace.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the workspace was created (ISO 8601 format).
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the workspace was last updated (ISO 8601 format).
</ResponseField>

---

## Create Call Agent

*Create a new agent for a workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
Name of the agent being created.
</ParamField>

<ParamField body="ttsModel" type="object" required>
Text-to-Speech (TTS) configuration for the agent.

<Expandable title="properties">

<ParamField body="provider" type="string" required>
TTS provider. Must be one of the following: openai, rime, elevenlabs, 11labs_byo, google.
</ParamField>

<ParamField body="voiceId" type="string" required>
The voice ID used for generating speech. e.g for Trillet Voices,
"mistv2_Wildflower" - Alt Female, Smart
"mistv2_Brook" - Male, Friendly
"mistv2_Violet" - Female, Professional
</ParamField>


<ParamField body="language" type="string" default='en' required>
Language code (e.g., en, fr).
</ParamField>

<ParamField body="elevenLabsApiKey" type="string">
ElevenLabs API key (required only when provider is "11labs_byo"). This will be encrypted and stored securely.
</ParamField>

</Expandable>
</ParamField>

<ParamField body="smartCallback" type="boolean" default="false">
Enable smart callback functionality for the agent.
</ParamField>

<ParamField body="maxAttemptsForSmartCallback" type="number" default="5">
Maximum number of callback attempts when smart callback is enabled.
</ParamField>

<ParamField body="gapBetweenEachAttemptForSmartCallback" type="array">
Array of time intervals between each callback attempt. Each item contains days and hours.

<Expandable title="Array Item Properties">

<ParamField body="days" type="number" default="1" min="0" max="30">
Number of days to wait before the next attempt.
</ParamField>

<ParamField body="hours" type="number" default="0" min="0" max="23">
Number of hours to wait before the next attempt.
</ParamField>

</Expandable>
</ParamField>

<ParamField body="phoneNumberIds" type="array">
Array of phone number IDs to associate with the agent.
</ParamField>

<ParamField body="llmModel" type="string" default='gpt-4o-mini' required>
Language Model to be used by the agent to generate responses. Must be one of: gpt-4o-mini, gpt-4o, gpt-4o-enterprise, gpt-4.1, gpt-4.1-mini, gpt-4.1-enterprise, gpt-4.1-mini-enterprise, gemini-2.5-flash, gemini-2.0-flash-001.
</ParamField>

<ParamField body="settings" type="object">
Additional settings for the agent.

<Expandable title="properties">

<ParamField body="speed" type="number" default="0.7">
Value between 0 and 1 that determines how fast the TTS narrates text.
</ParamField>

<ParamField body="volume" type="number" default="1">
Value between 0 and 1 that adjusts the TTS volume.
</ParamField>

<ParamField body="temperature" type="number" default="0.7">
Value between 0 and 1 for controlling the creativity of the LLM.
</ParamField>

</Expandable>
</ParamField>

<ParamField body="variables" type="object">
Custom variables to store for the agent.
</ParamField>

## Response Fields

<ResponseField name="_id" type="string">
Unique identifier for the newly created agent.
</ResponseField>

<ResponseField name="workspaceId" type="string">
Workspace ID associated with the agent.
</ResponseField>

<ResponseField name="userId" type="string">
User ID of the agent creator.
</ResponseField>

<ResponseField name="name" type="string">
Name of the agent.
</ResponseField>

<ResponseField name="ttsModel" type="object">
Text-to-Speech configuration for the agent.

<ResponseField name="provider" type="string">
TTS provider used by the agent.
</ResponseField>

<ResponseField name="voiceId" default="mistv2_Wildflower" type="string">
Voice ID used for generating speech. (e.g., mistv2_Brook, mistv2_Violet, mistv2_Wildflower)
</ResponseField>


<ResponseField name="language" type="string">
Language code of the TTS voice.
</ResponseField>

<ResponseField name="elevenLabsApiKey" type="string">
Encrypted ElevenLabs API key (only present if provider is "11labs_byo").
</ResponseField>
</ResponseField>

<ResponseField name="llmModel" type="string">
Language Model used by the agent to generate responses.
</ResponseField>

<ResponseField name="smartCallback" type="boolean">
Whether smart callback is enabled for the agent.
</ResponseField>

<ResponseField name="maxAttemptsForSmartCallback" type="number">
Maximum number of callback attempts.
</ResponseField>

<ResponseField name="gapBetweenEachAttemptForSmartCallback" type="array">
Array of time intervals between callback attempts.
</ResponseField>

<ResponseField name="phoneNumberIds" type="array">
Array of phone number IDs associated with the agent.
</ResponseField>

<ResponseField name="activeSessions" type="array">
Array of active sessions for the agent.
</ResponseField>

<ResponseField name="settings" type="object">
Additional settings configured for the agent.
</ResponseField>

<ResponseField name="status" type="string">
Current status of the agent (pending, ready, or error).
</ResponseField>

<ResponseField name="currentNode" type="string">
Current node or state within the agent's flow.
</ResponseField>

<ResponseField name="variables" type="object">
Custom variables stored for the agent.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the agent was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
Timestamp when the agent was last updated.
</ResponseField>

<ResponseExample>
```json
{
  "name": "Customer Support Agent",
  "ttsModel": {
    "provider": "rime",
    "voiceId": "mistv2_Wildflower",
    "name": "Sophie",
    "language": "en"
  },
  "llmModel": "gpt-4o",
  "type": "voice",
  "smartCallback": true,
  "maxAttemptsForSmartCallback": 3,
  "gapBetweenEachAttemptForSmartCallback": [
    { "days": 1, "hours": 2 },
    { "days": 2, "hours": 0 },
    { "days": 3, "hours": 6 }
  ],
  "settings": {
    "speed": 0.8,
    "volume": 1,
    "temperature": 0.7
  }
}
```
</ResponseExample>

---

## Delete Call Agent

*Delete an existing agent*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="agentId" type="string" required>
  The unique identifier of the agent to delete
</ParamField>

### Response Fields

<ResponseField name="success" type="string">
  Boolean value indicating if it was a successful operation.
</ResponseField>

<ResponseField name="message" type="string">
  A message confirming the successful deletion of the agent.
</ResponseField>

<ResponseExample>

```json
{
  "success": true,
  "message": "Agent successfully deleted"
}
```

</ResponseExample>

---

## Get Call Agent

*Retrieve the details of a single call agent based on its unique identifier.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="agentId" type="string" required>
  The unique identifier of the agent.
</ParamField>

<ResponseExample>
```json
{
  "ttsModel": {
    "language": "en",
    "provider": "openai",
    "voiceId": "example-voice-id-1",
    "name": "ExampleVoice"
  },
  "_id": "example-agent-id-1",
  "workspaceId": "example-workspace-id-1",
  "userId": "example-user-id-1",
  "name": "Test-Agent-1",
  "llmModel": "gpt-4o-mini",
  "type": "voice",
  "settings": {
    "speed": 0.7,
    "volume": 1,
    "temperature": 0.7
  },
  "status": "ready",
  "activeSessions": [],
  "createdAt": "2025-01-19T02:57:27.923Z",
  "updatedAt": "2025-01-19T02:57:27.923Z"
}
```
</ResponseExample>

### Response Fields

<ResponseField name="ttsModel" type="object">
  Contains the text-to-speech model details.
</ResponseField>

<ResponseField name="ttsModel.language" type="string">
  The language of the voice model (e.g., `en`).
</ResponseField>

<ResponseField name="ttsModel.provider" type="string">
  The TTS provider name (e.g., `openai`, `cartesia`).
</ResponseField>

<ResponseField name="ttsModel.voiceId" type="string">
  The unique identifier for the voice model.
</ResponseField>

<ResponseField name="ttsModel.name" type="string">
  The name of the voice model.
</ResponseField>

<ResponseField name="_id" type="string">
  Unique identifier for the agent.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  Unique identifier for the workspace associated with the agent.
</ResponseField>

<ResponseField name="userId" type="string">
  Unique identifier for the user associated with the agent.
</ResponseField>

<ResponseField name="name" type="string">
  Name of the agent.
</ResponseField>

<ResponseField name="llmModel" type="string">
  The LLM (language model) used by the agent (e.g., `gpt-4o-mini`).
</ResponseField>

<ResponseField name="type" type="string">
  Type of agent (e.g., `voice`).
</ResponseField>

<ResponseField name="settings" type="object">
  The settings for the agent, including `speed`, `volume`, and `temperature`.
</ResponseField>

<ResponseField name="settings.speed" type="number">
  Speed value for TTS narration (0 to 1).
</ResponseField>

<ResponseField name="settings.volume" type="number">
  Volume level for TTS (0 to 1).
</ResponseField>

<ResponseField name="settings.temperature" type="number">
  Temperature for LLM creativity (0 to 1).
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the agent (e.g., `ready`).
</ResponseField>

<ResponseField name="activeSessions" type="array">
  A list of active sessions associated with the agent.
</ResponseField>

<ResponseField name="createdAt" type="string">
  The timestamp when the agent was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  The timestamp when the agent was last updated.
</ResponseField>

---

## List Call Agents

*Retrieve a list of all call agents with all their details.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

<ResponseExample>
```json
[
  {
    "ttsModel": {
      "language": "en",
      "provider": "openai",
      "voiceId": "example-voice-id-1",
      "name": "ExampleVoice"
    },
    "_id": "example-agent-id-1",
    "workspaceId": "example-workspace-id-1",
    "userId": "example-user-id-1",
    "name": "Test-Agent-1",
    "llmModel": "gpt-4o-mini",
    "type": "voice",
    "settings": {
      "speed": 0.7,
      "volume": 1,
      "temperature": 0.7
    },
    "status": "ready",
    "activeSessions": [],
    "createdAt": "2025-01-19T02:57:27.923Z",
    "updatedAt": "2025-01-19T02:57:27.923Z"
  },
  {
    "ttsModel": {
      "language": "en",
      "provider": "cartesia",
      "voiceId": "example-voice-id-2",
      "name": "Sarah"
    },
    "_id": "example-agent-id-2",
    "workspaceId": "example-workspace-id-2",
    "userId": "example-user-id-2",
    "name": "New-Agent",
    "llmModel": "gpt-4o-mini",
    "type": "voice",
    "settings": {
      "speed": 0,
      "volume": 1,
      "temperature": 0.7
    },
    "status": "ready",
    "activeSessions": [
      {
        "roomName": "example-room-1",
        "startTime": "2025-01-16T14:46:36.883Z",
        "status": "active",
        "_id": "example-session-id-1"
      },
      {
        "roomName": "example-room-2",
        "startTime": "2025-01-16T21:10:47.518Z",
        "status": "active",
        "_id": "example-session-id-2"
      }
    ],
    "createdAt": "2024-12-27T10:49:04.175Z",
    "updatedAt": "2025-01-17T09:09:47.887Z"
  }
]
```
</ResponseExample>

### Response Fields

<ResponseField name="ttsModel" type="object">
  Contains the text-to-speech model details.
</ResponseField>

<ResponseField name="ttsModel.language" type="string">
  The language of the voice model (e.g., `en`).
</ResponseField>

<ResponseField name="ttsModel.provider" type="string">
  The TTS provider name (e.g., `openai`, `cartesia`).
</ResponseField>

<ResponseField name="ttsModel.voiceId" type="string">
  The unique identifier for the voice model.
</ResponseField>

<ResponseField name="ttsModel.name" type="string">
  The name of the voice model.
</ResponseField>

<ResponseField name="_id" type="string">
  Unique identifier for the agent.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  Unique identifier for the workspace associated with the agent.
</ResponseField>

<ResponseField name="userId" type="string">
  Unique identifier for the user associated with the agent.
</ResponseField>

<ResponseField name="name" type="string">
  Name of the agent.
</ResponseField>

<ResponseField name="llmModel" type="string">
  The LLM (language model) used by the agent (e.g., `gpt-4o-mini`).
</ResponseField>

<ResponseField name="type" type="string">
  Type of agent (e.g., `voice`).
</ResponseField>

<ResponseField name="settings" type="object">
  The settings for the agent, including `speed`, `volume`, and `temperature`.
</ResponseField>

<ResponseField name="settings.speed" type="number">
  Speed value for TTS narration (0 to 1).
</ResponseField>

<ResponseField name="settings.volume" type="number">
  Volume level for TTS (0 to 1).
</ResponseField>

<ResponseField name="settings.temperature" type="number">
  Temperature for LLM creativity (0 to 1).
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the agent (e.g., `ready`).
</ResponseField>

<ResponseField name="activeSessions" type="array">
  A list of active sessions associated with the agent.
</ResponseField>

<ResponseField name="createdAt" type="string">
  The timestamp when the agent was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  The timestamp when the agent was last updated.
</ResponseField>

---

## Update Call Agent

*Update an existing agent*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="agentId" type="string" required>
The unique identifier of the agent to update.
</ParamField>

## Request Body

<ParamField body="name" type="string">
New name for the agent.
</ParamField>

<ParamField body="llmModel" type="string" default='gpt-4o-mini' required>
New language model to be used by the agent to generate responses. Must be one of: gpt-4o-mini, gpt-4o-enterprise, gpt-4.1, gpt-4.1-mini, gemini-2.5-flash-preview-native-audio-dialog, gemini-2.5-flash, gemini-live-2.5-flash-preview, geminiaudiopipeline:gemini-2.5-flash-preview-native-audio-dialog, gemini-2.0-flash-live-001, gpt-5.
</ParamField>

<ParamField body="ttsModel" type="object">
Text-to-Speech configuration updates.

<Expandable title="Voice Settings">

<ParamField body="provider" type="string" required>
The text-to-speech provider. Must be one of: openai, rime, elevenlabs, 11labs_byo, google.
</ParamField>

<ParamField body="voiceId" type="string">
The voice ID used for generating speech. e.g for Trillet Voices,
"mistv2_Wildflower" - Alt Female, Smart
"mistv2_Brook" - Male, Friendly
"mistv2_Violet" - Female, Professional
</ParamField>

<ParamField body="language" type="string">
Language code (e.g., en, fr).
</ParamField>

<ParamField body="elevenLabsApiKey" type="string">
ElevenLabs API key (required only when provider is "11labs_byo"). Will be encrypted and stored securely. Set to null to remove existing key.
</ParamField>

</Expandable>
</ParamField>

<ParamField body="smartCallback" type="boolean" default="false">
Enable smart callback functionality for the agent.
</ParamField>

<ParamField body="maxAttemptsForSmartCallback" type="number" default="5">
Maximum number of callback attempts when smart callback is enabled.
</ParamField>

<ParamField body="gapBetweenEachAttemptForSmartCallback" type="array">
Array of time intervals between each callback attempt. Each item contains days and hours.

<Expandable title="Array Item Properties">

<ParamField body="days" type="number" default="1" min="0" max="30">
Number of days to wait before the next attempt.
</ParamField>

<ParamField body="hours" type="number" default="0" min="0" max="23">
Number of hours to wait before the next attempt.
</ParamField>

</Expandable>
</ParamField>

<ParamField body="phoneNumberIds" type="array">
Array of phone number IDs to associate with the agent.
</ParamField>

<ParamField body="settings" type="object">
Additional settings for the agent.

<Expandable title="properties">

<ParamField body="speed" type="number">
Value between 0 and 1 that determines how fast the TTS narrates text.
</ParamField>

<ParamField body="volume" type="number">
Value between 0 and 1 that adjusts the TTS volume.
</ParamField>

<ParamField body="temperature" type="number">
Value between 0 and 1 for controlling the creativity of the LLM.
</ParamField>

</Expandable>
</ParamField>

<ParamField body="variables" type="object">
Custom variables to store for the agent.
</ParamField>

## Response Fields

<ResponseField name="_id" type="string">
The unique identifier of the agent.
</ResponseField>

<ResponseField name="workspaceId" type="string">
The workspace identifier to which the agent belongs.
</ResponseField>

<ResponseField name="userId" type="string" optional="true">
The user identifier associated with the agent, if applicable.
</ResponseField>

<ResponseField name="name" type="string">
The name assigned to the agent.
</ResponseField>

<ResponseField name="ttsModel" type="object">
The configuration of the text-to-speech model used by the agent.

<ResponseField name="provider" type="string">
The provider of the TTS service.
</ResponseField>

<ResponseField name="voiceId" type="string">
The specific voice ID used in the TTS model.
</ResponseField>

<ResponseField name="name" type="string">
The name of the TTS model configuration.
</ResponseField>

<ResponseField name="language" type="string">
The language set for the TTS model.
</ResponseField>

<ResponseField name="elevenLabsApiKey" type="string">
Encrypted ElevenLabs API key (only present if provider is "11labs_byo").
</ResponseField>
</ResponseField>

<ResponseField name="llmModel" type="string">
The large language model used by the agent.
</ResponseField>

<ResponseField name="smartCallback" type="boolean">
Whether smart callback functionality is enabled.
</ResponseField>

<ResponseField name="phoneNumberIds" type="array">
Array of phone number IDs associated with the agent.
</ResponseField>

<ResponseField name="activeSessions" type="array">
A list of active sessions associated with the agent.

<ResponseField name="roomName" type="string">
The name of the room for the session.
</ResponseField>

<ResponseField name="participantId" type="string">
The participant identifier in the session.
</ResponseField>

<ResponseField name="startTime" type="date">
The start time of the session.
</ResponseField>

<ResponseField name="status" type="string">
The status of the session.
</ResponseField>
</ResponseField>

<ResponseField name="settings" type="object">
Any custom settings configured for the agent.
</ResponseField>

<ResponseField name="status" type="string">
The current status of the agent, such as "pending", "ready", or "error".
</ResponseField>

<ResponseField name="currentNode" type="string">
The current node or state within the agent's flow or logic.
</ResponseField>

<ResponseField name="variables" type="object">
Custom variables stored for the agent.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the agent was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
Timestamp when the agent was last updated.
</ResponseField>

<ResponseExample>

```json
{
  "name": "Updated Customer Support Agent",
  "llmModel": "claude-3-5-sonnet-latest",
  "ttsModel": {
    "provider": "11labs_byo",
    "voiceId": "21m00Tcm4TlvDq8ikWAM",
    "name": "Premium Voice",
    "language": "en",
    "elevenLabsApiKey": "your-new-elevenlabs-api-key"
  },
  "smartCallback": true,
  "maxAttemptsForSmartCallback": 5,
  "gapBetweenEachAttemptForSmartCallback": [
    { "days": 1, "hours": 0 },
    { "days": 1, "hours": 12 },
    { "days": 2, "hours": 0 },
    { "days": 3, "hours": 0 },
    { "days": 7, "hours": 0 }
  ],
  "settings": {
    "speed": 0.9,
    "volume": 0.8,
    "temperature": 0.6
  }
}
```
</ResponseExample>

---

## Create Omni Flow Agent

*Create a new agent for a workspace.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>  
Workspace identifier for the API.  
</ParamField>  

### Request Body  

<ParamField body="name" type="string" required>  
Name of the agent being created.  
</ParamField>  

<ParamField body="llmModel" type="string" default='gpt-4o-mini' required>  
Language Model to be used by the agent to generate responses. (e.g. gpt-4o-mini, gpt-4o, gpt-4o-enterprise)  
</ParamField>  

<ParamField body="settings" type="object" optional>  
Settings related to the agent. 
</ParamField>  

### Response Fields  

<ResponseField name="workspaceId" type="string">  
Workspace ID associated with the agent.  
</ResponseField>  

<ResponseField name="userId" type="string">  
User ID of the agent creator.  
</ResponseField>  

<ResponseField name="name" type="string">  
Name of the agent.  
</ResponseField>  

<ResponseField name="llmModel" type="string">  
Language model used by the agent (e.g., `gpt-4o-mini`).  
</ResponseField>  

<ResponseField name="phoneNumberId" type="string" nullable>  
Phone number ID, if assigned to the agent.  
</ResponseField>  

<ResponseField name="status" type="string">  
Current status of the agent (e.g., `ready`).  
</ResponseField>  

<ResponseField name="createdAt" type="string">  
Timestamp when the agent was created.  
</ResponseField>  

<ResponseField name="updatedAt" type="string">  
Timestamp when the agent was last updated.  
</ResponseField>  

<ResponseExample>  
```json  
{  
  "workspaceId": "01a0sda156scx5f8",  
  "userId": "01a0sda156scx5f8",  
  "name": "ExampleOmniFlowAgent",  
  "llmModel": "gpt-4o-mini",  
  "phoneNumberId": null,  
  "status": "ready",  
  "createdAt": "2025-01-19T03:18:22.604Z",  
  "updatedAt": "2025-01-19T03:18:22.604Z"  
}  
```  
</ResponseExample>

---

## Delete Omni Flow Agent

*Delete an existing agent*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="agentId" type="string" required>
  The unique identifier of the agent to delete
</ParamField>

### Response Fields

<ResponseField name="success" type="string">
  Boolean value indicating if it was a successful operation.
</ResponseField>

<ResponseField name="message" type="string">
  A message confirming the successful deletion of the agent.
</ResponseField>

<ResponseExample>

```json
{
  "success": true,
  "message": "Agent successfully deleted"
}
```

</ResponseExample>

---

## Get Omni Flow Agent

*Retrieve the details of a single call agent based on its unique identifier.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the agent.
</ParamField>

<ResponseExample>
```json
{
  "workspaceId": "674b9687d56a35c024db9cce",
  "userId": "674b9687d56a35c024db9ccc",
  "name": "test",
  "llmModel": "gpt-4o-mini",
  "phoneNumberId": null,
  "status": "ready",
  "createdAt": "2025-01-19T03:18:22.604Z",
  "updatedAt": "2025-01-19T03:18:22.604Z",
  "messageChannel": "SMS"
}
```
</ResponseExample>

### Response Fields

<ResponseField name="workspaceId" type="string">
  Workspace ID associated with the agent.
</ResponseField>

<ResponseField name="userId" type="string">
  User ID of the agent creator.
</ResponseField>

<ResponseField name="name" type="string">
  Name of the agent.
</ResponseField>

<ResponseField name="llmModel" type="string">
  Language model used by the agent (e.g., `gpt-4o-mini`).
</ResponseField>

<ResponseField name="phoneNumberId" type="object" nullable>
  The phone number ID associated with the agent, if available.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the agent (e.g., `ready`).
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the agent was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the agent was last updated.
</ResponseField>

<ResponseField name="messageChannel" type="string">
  The channel used by the agent for communication (e.g., `SMS`).
</ResponseField>

---

## List Omni Flow Agents

*Retrieve a list of all call agents with all their details.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

<ResponseExample>
```json
[
  {
    "workspaceId": "674b9687d56a35c024db9cce",
    "userId": "674b9687d56a35c024db9ccc",
    "name": "test",
    "llmModel": "gpt-4o-mini",
    "phoneNumberId": null,
    "status": "ready",
    "createdAt": "2025-01-19T03:18:22.604Z",
    "updatedAt": "2025-01-19T03:18:22.604Z",
    "messageChannel": "SMS"
  },
  {
    "workspaceId": "674b9687d56a35c024db9cce",
    "userId": "674b9687d56a35c024db9ccc",
    "name": "test",
    "llmModel": "gpt-4o-mini",
    "phoneNumberId": {},
    "status": "ready",
    "createdAt": "2025-01-06T09:13:50.282Z",
    "updatedAt": "2025-01-06T09:16:15.796Z",
    "messageChannel": "SMS"
  }
]
```
</ResponseExample>

### Response Fields

<ResponseField name="workspaceId" type="string">
  Workspace ID associated with the agent.
</ResponseField>

<ResponseField name="userId" type="string">
  User ID of the agent creator.
</ResponseField>

<ResponseField name="name" type="string">
  Name of the agent.
</ResponseField>

<ResponseField name="llmModel" type="string">
  Language model used by the agent (e.g., `gpt-4o-mini`).
</ResponseField>

<ResponseField name="phoneNumberId" type="object" nullable>
  The phone number ID associated with the agent, if available.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the agent (e.g., `ready`).
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the agent was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the agent was last updated.
</ResponseField>

<ResponseField name="messageChannel" type="string">
  The channel used by the agent for communication (e.g., `SMS`).
</ResponseField>

---

## Update Omni Flow Agent

*Update an existing agent*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="agentId" type="string" required>
  The unique identifier of the agent to update
</ParamField>

### Request Body

<ParamField body="name" type="string">
  New name for the agent
</ParamField>

<ParamField body="llmModel" type="string">
  New language model to use
</ParamField>

<ParamField body="ttsModel" type="object">
  <Expandable title="Voice Settings">
    <ParamField body="provider" type="string">
      The text-to-speech provider
    </ParamField>
    <ParamField body="voiceId" type="string">
      The voice identifier
    </ParamField>
  </Expandable>
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the OmniFlowAgent.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the OmniFlowAgent is configured.
</ResponseField>

<ResponseField name="userId" type="string" optional="true">
  The identifier of the user associated with the OmniFlowAgent, if any.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the OmniFlowAgent.
</ResponseField>

<ResponseField name="llmModel" type="string">
  The language model used by the OmniFlowAgent, such as 'gpt-4o-mini'.
</ResponseField>

<ResponseField name="phoneNumberId" type="string" optional="true">
  The identifier of the phone number associated with the OmniFlowAgent.
</ResponseField>

<ResponseField name="settings" type="object">
  A flexible schema for storing custom settings related to the OmniFlowAgent.
</ResponseField>

<ResponseField name="status" type="string">
  The operational status of the OmniFlowAgent, such as 'pending', 'ready', or
  'error'.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the conversation was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the conversation was last updated.
</ResponseField>
<ResponseExample>

```json
{
  "_id": "agentIdExample",
  "workspaceId": "workspaceIdExample",
  "userId": "userIdExample",
  "name": "Updated Agent Name",
  "llmModel": "gpt-4o-mini",
  "phoneNumberId": "phoneNumberIdExample",
  "settings": {
    "customSetting": "value"
  },
  "status": "ready",
  "createdAt": "2025-01-01T12:00:00Z",
  "updatedAt": "2025-01-02T12:00:00Z"
}
```

</ResponseExample>

---

## Cancel Batch Operation

*Cancel a batch call operation and stop any remaining calls from being processed*

### Headers
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="batchId" type="string" required>
  The unique identifier of the batch call operation to cancel
</ParamField>

### Response

<ResponseField name="batchId" type="string">
  The ID of the cancelled batch
</ResponseField>

<ResponseField name="status" type="string">
  New status of the batch (will be "cancelled")
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message about the cancellation
</ResponseField>

<ResponseField name="details" type="object">
  Summary of the cancellation impact
  <Expandable title="Details Object">
    <ResponseField name="completedCalls" type="number">
      Number of calls that were already completed
    </ResponseField>
    <ResponseField name="failedCalls" type="number">
      Number of calls that had already failed
    </ResponseField>
    <ResponseField name="cancelledCalls" type="number">
      Number of calls that were cancelled (waiting + active)
    </ResponseField>
    <ResponseField name="totalCalls" type="number">
      Total number of calls in the batch
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Usage

```bash
curl -X DELETE "https://api.trillet.ai/v1/batch-calls/batch_7891011121314" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"
```

### Example Response

```json
{
  "batchId": "batch_7891011121314",
  "status": "cancelled",
  "message": "Batch cancelled successfully",
  "details": {
    "completedCalls": 95,
    "failedCalls": 5,
    "cancelledCalls": 50,
    "totalCalls": 150
  }
}
```

### Cancellation Behavior

When you cancel a batch operation:

1. **Queued Calls**: All calls waiting in the queue are immediately cancelled and will not be processed
2. **Active Calls**: Currently active calls will continue to completion but no new calls will start
3. **Completed Calls**: Already completed calls are not affected
4. **Batch Status**: The batch status is updated to "cancelled" 
5. **History**: The cancellation is recorded in the batch history

### Error Responses

<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>

<ResponseField name="message" type="string">
  Additional context about the error
</ResponseField>

<ResponseField name="id" type="string">
  The batch ID that was not found (for 404 errors)
</ResponseField>

**Common Error Codes:**
- `404` - Batch not found with the specified ID
- `500` - Server error during cancellation process

### Use Cases

- Stop a batch operation that was started with incorrect data
- Cancel remaining calls when you've achieved your campaign goals
- Emergency stop for batch operations
- Cost control by stopping long-running batches

### Important Notes

- Cancellation cannot be undone
- You will still be charged for completed calls
- Active calls at the time of cancellation will finish normally
- The batch cannot be restarted after cancellation

---

## Get Individual Call Status

*Get the status of an individual call within a batch operation*

### Headers
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="batchId" type="string" required>
  The unique identifier of the batch call operation
</ParamField>

<ParamField path="jobId" type="string" required>
  The unique identifier of the individual call job
</ParamField>

### Response

<ResponseField name="jobId" type="string">
  The unique identifier of the call job
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the individual call
  - `waiting` - Call is queued and waiting to be processed
  - `active` - Call is currently in progress
  - `completed` - Call completed successfully
  - `failed` - Call failed due to an error
</ResponseField>

<ResponseField name="phone_number" type="string">
  The phone number that was called
</ResponseField>

<ResponseField name="startTime" type="number">
  Timestamp when the call started (if applicable)
</ResponseField>

<ResponseField name="endTime" type="number">
  Timestamp when the call ended (if completed or failed)
</ResponseField>

<ResponseField name="duration" type="number">
  Duration of the call in seconds (if completed)
</ResponseField>

<ResponseField name="error" type="string">
  Error message if the call failed
</ResponseField>

<ResponseField name="result" type="object">
  Call result data including conversation details (if completed)
</ResponseField>

### Example Usage

```bash
curl -X GET "https://api.trillet.ai/v1/api/batch-calls/batch_7891011121314/calls/call_123" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"
```

### Example Response (Completed Call)

```json
{
  "jobId": "call_123",
  "status": "completed",
  "phone_number": "+1234567890",
  "startTime": 1703097600000,
  "endTime": 1703097642000,
  "duration": 42,
  "result": {
    "callId": "call_abc123",
    "transcript": "Hello John, this is an automated call...",
    "outcome": "successful",
    "metadata": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    }
  }
}
```

### Example Response (Failed Call)

```json
{
  "jobId": "call_124",
  "status": "failed",
  "phone_number": "+1987654321",
  "startTime": 1703097600000,
  "endTime": 1703097615000,
  "error": "Number busy - unable to connect after 3 attempts"
}
```

### Example Response (Active Call)

```json
{
  "jobId": "call_125",
  "status": "active",
  "phone_number": "+1555666777",
  "startTime": 1703097700000
}
```

### Error Responses

<ResponseField name="status" type="string">
  Will be "not_found" if the call doesn't exist
</ResponseField>

<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>

**Common Error Codes:**
- `404` - Call not found with the specified job ID
- `500` - Server error retrieving call status

### Use Cases

- Monitor individual call progress within a batch
- Retrieve detailed results for completed calls
- Debug failed calls to understand failure reasons
- Track call timing and duration metrics

---

## Get Batch Progress

*Get detailed progress information for a batch call operation*

### Headers
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="batchId" type="string" required>
  The unique identifier of the batch call operation
</ParamField>

### Response

<ResponseField name="status" type="string">
  Current status of the batch operation
</ResponseField>

<ResponseField name="isComplete" type="boolean">
  Whether the batch operation has finished
</ResponseField>

<ResponseField name="waiting" type="number">
  Number of calls waiting in queue
</ResponseField>

<ResponseField name="active" type="number">
  Number of calls currently being processed
</ResponseField>

<ResponseField name="completed" type="number">
  Number of successfully completed calls
</ResponseField>

<ResponseField name="failed" type="number">
  Number of failed calls
</ResponseField>

<ResponseField name="total" type="number">
  Total number of calls in the batch
</ResponseField>

<ResponseField name="startTime" type="number">
  Timestamp when the batch started processing
</ResponseField>

<ResponseField name="lastCompletedTime" type="number">
  Timestamp of the last completed call
</ResponseField>

<ResponseField name="completedTime" type="number">
  Timestamp when the batch was completed (if finished)
</ResponseField>

<ResponseField name="averageCallDuration" type="number">
  Average duration of completed calls in seconds
</ResponseField>

<ResponseField name="recent_calls" type="array">
  Array of recent call results for monitoring
</ResponseField>

### Example Usage

```bash
curl -X GET "https://api.trillet.ai/v1/api/batch-calls/batch_7891011121314/status" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"
```

### Example Response

```json
{
  "status": "processing",
  "isComplete": false,
  "waiting": 45,
  "active": 5,
  "completed": 95,
  "failed": 5,
  "total": 150,
  "startTime": 1703097600000,
  "lastCompletedTime": 1703101200000,
  "completedTime": null,
  "averageCallDuration": 45.2,
  "recent_calls": [
    {
      "jobId": "call_123",
      "status": "completed",
      "phone_number": "+1234567890",
      "completedAt": 1703101200000,
      "duration": 42
    },
    {
      "jobId": "call_124", 
      "status": "failed",
      "phone_number": "+1987654321",
      "failedAt": 1703101150000,
      "error": "Number busy"
    }
  ]
}
```

### Error Responses

<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>

**Common Error Codes:**
- `500` - Server error retrieving batch progress information

### Progress Tracking

This endpoint provides real-time progress updates for your batch call operations. Use it to build dashboards or monitor batch completion in your applications.

---

## Get Batch Status

*Get detailed status information for a batch call operation*

### Headers
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="batchId" type="string" required>
  The unique identifier of the batch call operation
</ParamField>

### Response

<ResponseField name="id" type="string">
  The batch ID
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the batch operation
  - `queued` - Batch is waiting to be processed
  - `processing` - Calls are currently being made
  - `completed` - All calls have been completed
  - `cancelled` - Batch was cancelled
  - `failed` - Batch failed due to an error
</ResponseField>

<ResponseField name="isComplete" type="boolean">
  Whether the batch operation has finished
</ResponseField>

<ResponseField name="totalCalls" type="number">
  Total number of calls in the batch
</ResponseField>

<ResponseField name="progress" type="object">
  Detailed progress information
  <Expandable title="Progress Object">
    <ResponseField name="waiting" type="number">
      Number of calls waiting in queue
    </ResponseField>
    <ResponseField name="active" type="number">
      Number of calls currently being processed
    </ResponseField>
    <ResponseField name="completed" type="number">
      Number of successfully completed calls
    </ResponseField>
    <ResponseField name="failed" type="number">
      Number of failed calls
    </ResponseField>
    <ResponseField name="total" type="number">
      Total number of calls in the batch
    </ResponseField>
    <ResponseField name="startTime" type="number">
      Timestamp when the batch started processing
    </ResponseField>
    <ResponseField name="lastCompletedTime" type="number">
      Timestamp of the last completed call
    </ResponseField>
    <ResponseField name="completedTime" type="number">
      Timestamp when the batch was completed (if finished)
    </ResponseField>
    <ResponseField name="averageCallDuration" type="number">
      Average duration of completed calls in seconds
    </ResponseField>
    <ResponseField name="recent_calls" type="array">
      Array of recent call results for monitoring
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="number">
  Timestamp of when this status was retrieved
</ResponseField>

### Example Usage

```bash
curl -X GET "https://api.trillet.ai/v1/api/batch-calls/batch_7891011121314" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"
```

### Example Response

```json
{
  "id": "batch_7891011121314",
  "status": "processing",
  "isComplete": false,
  "totalCalls": 150,
  "progress": {
    "waiting": 45,
    "active": 5,
    "completed": 95,
    "failed": 5,
    "total": 150,
    "startTime": 1703097600000,
    "lastCompletedTime": 1703101200000,
    "completedTime": null,
    "averageCallDuration": 45.2,
    "recent_calls": [
      {
        "jobId": "call_123",
        "status": "completed",
        "phone_number": "+1234567890",
        "completedAt": 1703101200000
      }
    ]
  },
  "timestamp": 1703101300000
}
```

### Error Responses

<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>

<ResponseField name="message" type="string">
  Additional context about the error
</ResponseField>

**Common Error Codes:**
- `404` - Batch not found with the specified ID
- `500` - Server error retrieving batch information

### Status Monitoring

You can poll this endpoint to monitor the progress of your batch calls. The response includes detailed metrics about call completion rates, timing information, and recent call results.

---

## List Batch Calls

*Get a paginated list of all calls within a batch operation with optional status filtering*

### Headers
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="batchId" type="string" required>
  The unique identifier of the batch call operation
</ParamField>

### Query Parameters

<ParamField query="page" type="number" default="1">
  Page number for pagination (1-based)
</ParamField>

<ParamField query="limit" type="number" default="20">
  Number of results per page (maximum 100)
</ParamField>

<ParamField query="status" type="string" default="all">
  Filter calls by status
  - `all` - Return all calls regardless of status
  - `waiting` - Only calls waiting in queue
  - `active` - Only calls currently in progress
  - `completed` - Only successfully completed calls
  - `failed` - Only failed calls
</ParamField>

### Response

<ResponseField name="calls" type="array">
  Array of call objects in the batch
  <Expandable title="Call Object">
    <ResponseField name="jobId" type="string">
      Unique identifier of the call job
    </ResponseField>
    <ResponseField name="status" type="string">
      Current status of the call
    </ResponseField>
    <ResponseField name="phone_number" type="string">
      Phone number that was called
    </ResponseField>
    <ResponseField name="startTime" type="number">
      Timestamp when the call started (if applicable)
    </ResponseField>
    <ResponseField name="endTime" type="number">
      Timestamp when the call ended (if completed/failed)
    </ResponseField>
    <ResponseField name="duration" type="number">
      Call duration in seconds (if completed)
    </ResponseField>
    <ResponseField name="error" type="string">
      Error message (if failed)
    </ResponseField>
    <ResponseField name="metadata" type="object">
      Customer data from CSV row
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination information
  <Expandable title="Pagination Object">
    <ResponseField name="page" type="number">
      Current page number
    </ResponseField>
    <ResponseField name="limit" type="number">
      Results per page
    </ResponseField>
    <ResponseField name="total" type="number">
      Total number of calls matching the filter
    </ResponseField>
    <ResponseField name="totalPages" type="number">
      Total number of pages
    </ResponseField>
    <ResponseField name="hasNext" type="boolean">
      Whether there are more pages
    </ResponseField>
    <ResponseField name="hasPrev" type="boolean">
      Whether there are previous pages
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object">
  Summary statistics for the batch
  <Expandable title="Summary Object">
    <ResponseField name="total" type="number">
      Total calls in batch
    </ResponseField>
    <ResponseField name="waiting" type="number">
      Calls waiting in queue
    </ResponseField>
    <ResponseField name="active" type="number">
      Calls currently active
    </ResponseField>
    <ResponseField name="completed" type="number">
      Successfully completed calls
    </ResponseField>
    <ResponseField name="failed" type="number">
      Failed calls
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Usage

```bash
# Get first page of all calls
curl -X GET "https://api.trillet.ai/v1/api/batch-calls/batch_7891011121314/calls" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

# Get failed calls only, page 2
curl -X GET "https://api.trillet.ai/v1/api/batch-calls/batch_7891011121314/calls?status=failed&page=2&limit=50" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"
```

### Example Response

```json
{
  "calls": [
    {
      "jobId": "call_123",
      "status": "completed",
      "phone_number": "+1234567890",
      "startTime": 1703097600000,
      "endTime": 1703097642000,
      "duration": 42,
      "metadata": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com"
      }
    },
    {
      "jobId": "call_124",
      "status": "failed",
      "phone_number": "+1987654321",
      "startTime": 1703097600000,
      "endTime": 1703097615000,
      "error": "Number busy",
      "metadata": {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane.smith@example.com"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  },
  "summary": {
    "total": 150,
    "waiting": 45,
    "active": 5,
    "completed": 95,
    "failed": 5
  }
}
```

### Error Responses

<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>

**Common Error Codes:**
- `500` - Server error retrieving batch calls

### Use Cases

- Build dashboards showing all calls in a batch
- Filter and review failed calls for troubleshooting
- Export call results for reporting and analysis
- Monitor active calls in real-time

---

## Batch Calls Overview

*Efficiently make multiple AI-powered calls using CSV data uploads*

## Introduction

The Batch Calls API allows you to initiate multiple AI-powered phone calls simultaneously using a CSV file containing contact information. This feature is perfect for marketing campaigns, customer outreach, surveys, and other scenarios where you need to make calls to a large number of contacts.

## Key Features

- **CSV-based data upload** - Upload contact lists with custom fields for personalization
- **Template generation** - Download properly formatted CSV templates
- **Data validation** - Validate your CSV data before starting batch operations
- **Real-time monitoring** - Track progress and individual call status
- **Batch management** - Start, monitor, and cancel batch operations
- **Rate limit compliance** - Automatic queue management respecting your account limits

## Workflow

### 1. Prepare Your Data

Prepare your CSV file with the required columns:

```csv
phone_number,first_name,last_name,email,custom_field_1,custom_field_2
+1234567890,John,Doe,john.doe@example.com,Premium Customer,West Coast
+1987654321,Jane,Smith,jane.smith@example.com,Standard Customer,East Coast
```

### 2. Start Batch Operation

Start the batch call operation by uploading your CSV file and specifying the agent to use:

```bash
curl -X POST "https://api.trillet.ai/v1/batch-calls" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -F "file=@your-contacts.csv" \
  -F "agentId=agent_123456"
```

### 3. Monitor Progress

Track the progress of your batch operation in real-time:

```bash
curl -X GET "https://api.trillet.ai/v1/batch-calls/batch_7891011121314" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"
```

## CSV File Requirements

### Required Columns

- `phone_number` - Valid phone number in international format (e.g., +1234567890)

### Optional Columns

- `first_name` - First name for personalization
- `last_name` - Last name for personalization  
- `email` - Email address
- Custom fields - Any additional columns for dynamic variables

### File Specifications

- **Maximum file size:** 20MB
- **Supported format:** CSV (Comma-Separated Values)
- **Encoding:** UTF-8 recommended
- **Maximum records:** Varies by account plan

## Dynamic Variables

All CSV columns can be used as dynamic variables in your agent's script. For example, if your CSV has a `first_name` column, you can reference it in your agent's prompt as `{first_name}`.

```text
"Hello {first_name}, this is an automated call from {company_name}. 
We're reaching out to customers in {region} to..."
```

## Rate Limits and Processing

- Batch calls respect your account's rate limits
- Calls are queued and processed automatically
- Processing speed depends on your plan and current system load
- Failed calls are automatically retried based on failure reason

## Status Tracking

Each batch operation provides detailed status information:

- **Waiting:** Calls queued but not yet started
- **Active:** Calls currently in progress
- **Completed:** Successfully completed calls
- **Failed:** Calls that failed due to errors

## Error Handling

Common reasons for call failures:

- **Invalid phone number** - Number format is incorrect
- **Number unreachable** - Phone number doesn't exist or is disconnected
- **Busy signal** - Number is busy (retried automatically)
- **No answer** - Call went to voicemail or wasn't answered
- **Carrier blocked** - Call was blocked by the carrier

## Best Practices

### Data Preparation

- Clean your phone number data before upload
- Use consistent formatting for phone numbers
- Include personalization fields for better engagement
- Test with a small batch before running large campaigns

### Monitoring

- Monitor batch progress regularly
- Review failed calls and adjust data if needed
- Use individual call status for detailed troubleshooting
- Cancel batches early if issues are detected

### Compliance

- Ensure you have consent to call all numbers in your list
- Respect do-not-call lists and regulations
- Include opt-out mechanisms in your call scripts
- Follow local telecommunications regulations

## Pricing

Batch calls are charged per completed call attempt. Failed calls due to system errors are not charged, but calls that connect (even if they go to voicemail) are billable.

## Testing with Postman

Since the documentation's "Try Now" buttons don't support file uploads, here's how to test batch call endpoints using Postman:

### Start Batch Calls
- **Method:** POST
- **URL:** `https://api.trillet.ai/v1/api/batch-calls`
- **Headers:** 
  - `x-api-key: YOUR_API_KEY`
  - `x-workspace-id: YOUR_WORKSPACE_ID`
- **Body:** form-data
  - Key: `file`, Type: File, Value: [Select your CSV file]
  - Key: `agentId`, Type: Text, Value: `your_agent_id`

<Note>
  **Important:** The documentation's interactive "Try Now" buttons cannot handle file uploads. Always use cURL, Postman, or similar tools for testing endpoints that require file uploads.
</Note>

## Support

For technical support with batch call operations, contact our support team with your batch ID for faster assistance.

---

## Start Batch Calls

*Initiate a batch call operation using a CSV file and specified agent*

### Headers
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>
### Request Body
This endpoint accepts multipart/form-data with the following fields:
<ParamField body="file" type="file" required>
  CSV file containing the batch call data. Maximum file size: 20MB.
</ParamField>
<ParamField body="agentId" type="string" required>
  The ID of the agent that will be used to make the batch calls.
</ParamField>
<ParamField body="scheduledAt" type="string" optional>
  UTC datetime string in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ) to schedule the batch for future execution. If not provided, batch starts immediately.
</ParamField>
<ParamField body="smartCallbackConfig" type="string" optional>
  JSON string containing smart callback configuration. Format: `{"enabled": boolean, "maxAttempts": number, "gaps": [{"days": number, "hours": number}]}`
</ParamField>
<Note>
  **Testing Note**: The "Try Now" button in this documentation doesn't support file uploads. Use the cURL example below or a tool like Postman to test this endpoint.
</Note>
### CSV File Format
The CSV file should contain the following columns:
- `phone_number` - The phone number to call (required)
- `first_name` - First name for personalization
- `last_name` - Last name for personalization  
- `email` - Email address
- Additional custom fields for dynamic variables
### Response
<ResponseField name="batchId" type="string">
  Unique identifier for the batch call operation
</ResponseField>
<ResponseField name="totalCalls" type="number">
  Total number of calls that will be made in this batch
</ResponseField>
<ResponseField name="status" type="string">
  Current status of the batch operation (e.g., "queued", "processing")
</ResponseField>
<ResponseField name="message" type="string">
  Success message confirming the batch initiation
</ResponseField>
### Example Usage
```bash
# Basic batch call
curl -X POST "https://api.trillet.ai/v1/api/batch-calls" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -F "file=@batch-calls.csv" \
  -F "agentId=agent_123456"

# Scheduled batch call with smart callback
curl -X POST "https://api.trillet.ai/v1/api/batch-calls" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -F "file=@batch-calls.csv" \
  -F "agentId=agent_123456" \
  -F "scheduledAt=2024-01-15T14:30:00Z" \
  -F "smartCallbackConfig={\"enabled\": true, \"maxAttempts\": 3, \"gaps\": [{\"days\": 1, \"hours\": 0}]}"
```

### Example Response
```json
{
  "batchId": "batch_7891011121314",
  "totalCalls": 150,
  "status": "queued",
  "message": "Batch calls initiated successfully"
}
```

### Testing with Different Tools
<Tabs>
  <Tab title="cURL">
    ```bash
    # Basic usage
    curl -X POST "https://api.trillet.ai/v1/api/batch-calls" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "x-workspace-id: YOUR_WORKSPACE_ID" \
      -F "file=@batch-calls.csv" \
      -F "agentId=agent_123456"
    
    # With verbose output for debugging
    curl -v -X POST "https://api.trillet.ai/v1/api/batch-calls" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "x-workspace-id: YOUR_WORKSPACE_ID" \
      -F "file=@batch-calls.csv" \
      -F "agentId=agent_123456"

    # With scheduled time and smart callback
    curl -X POST "https://api.trillet.ai/v1/api/batch-calls" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "x-workspace-id: YOUR_WORKSPACE_ID" \
      -F "file=@batch-calls.csv" \
      -F "agentId=agent_123456" \
      -F "scheduledAt=2024-01-15T14:30:00Z" \
      -F "smartCallbackConfig={\"enabled\": true, \"maxAttempts\": 5, \"gaps\": [{\"days\": 1, \"hours\": 0}, {\"days\": 2, \"hours\": 0}]}"
    ```
  </Tab>

  <Tab title="JavaScript/Node.js">
    ```javascript
    const FormData = require('form-data');
    const fs = require('fs');
    const axios = require('axios');

    const form = new FormData();
    form.append('file', fs.createReadStream('batch-calls.csv'));
    form.append('agentId', 'agent_123456');
    
    // Optional: Schedule for future
    form.append('scheduledAt', '2024-01-15T14:30:00Z');
    
    // Optional: Smart callback configuration
    form.append('smartCallbackConfig', JSON.stringify({
      enabled: true,
      maxAttempts: 3,
      gaps: [
        { days: 1, hours: 0 },
        { days: 2, hours: 0 }
      ]
    }));

    const response = await axios.post('https://api.trillet.ai/v1/api/batch-calls', form, {
      headers: {
        ...form.getHeaders(),
        'x-api-key': 'YOUR_API_KEY',
        'x-workspace-id': 'YOUR_WORKSPACE_ID'
      }
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python
    import requests
    import json

    url = "https://api.trillet.ai/v1/api/batch-calls"
    headers = {
        'x-api-key': 'YOUR_API_KEY',
        'x-workspace-id': 'YOUR_WORKSPACE_ID'
    }

    files = {
        'file': open('batch-calls.csv', 'rb'),
        'agentId': (None, 'agent_123456'),
        'scheduledAt': (None, '2024-01-15T14:30:00Z'),  # Optional
        'smartCallbackConfig': (None, json.dumps({      # Optional
            "enabled": True,
            "maxAttempts": 3,
            "gaps": [{"days": 1, "hours": 0}]
        }))
    }

    response = requests.post(url, headers=headers, files=files)
    print(response.json())
    ```
  </Tab>
</Tabs>
### Processing Flow
1. **File Upload**: The CSV file is uploaded and validated
2. **Record Validation**: Each record in the CSV is validated for required fields
3. **Batch Preparation**: A batch configuration is created with the specified agent
4. **Queue Initialization**: Individual call jobs are queued for processing
5. **Execution**: Calls are made according to your account's rate limits (or at scheduled time)
### Error Responses
<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>
**Common Error Codes:**
- `400` - No file uploaded, no agent ID provided, or CSV validation failed
- `413` - File size exceeds 20MB limit
- `500` - Failed to prepare batch or start batch execution
### Rate Limits
Batch calls are subject to your account's rate limits. The system will automatically manage the call queue to respect these limits while maximizing throughput.

---

## Export Call History CSV

*Export call history records as a CSV file with optional transcript and post-analysis data.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Request Body

<ParamField body="includeTranscripts" type="boolean" default="false">
Whether to include full call transcripts in the export.
</ParamField>

<ParamField body="includePostAnalysis" type="boolean" default="false">
Whether to include post-call analysis data in the export.
</ParamField>

<ParamField body="limit" type="number">
Maximum number of records to export.
</ParamField>

<ParamField body="batchId" type="string">
Filter by batch call ID.
</ParamField>

<ParamField body="agentId" type="string">
Filter by agent ID.
</ParamField>

<ParamField body="status" type="string">
Filter by call status.
</ParamField>

<ParamField body="direction" type="string">
Filter by call direction.
</ParamField>

<ParamField body="dateRange" type="object">
Date range filter.

<Expandable title="properties">

<ParamField body="startDate" type="string">
Start date in ISO format.
</ParamField>

<ParamField body="endDate" type="string">
End date in ISO format.
</ParamField>

</Expandable>
</ParamField>

## Response

The response is streamed as a CSV file with `Content-Type: text/csv` and `Content-Disposition: attachment` headers.

The CSV includes columns for call ID, phone numbers, direction, status, duration, agent, flow name, cost, summary, variables, and optionally transcript and post-analysis data.

---

## Get Phone Numbers

*Retrieve a list of phone numbers associated with the user.*

### Headers

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Response Fields

<ResponseField name="phoneNumbers" type="array">
  An array of phone numbers associated with the user, in E.164 format.
</ResponseField>

### Example Response

<ResponseExample>
```json
{
  "_id": "123abc456def789gh012i345jkl6789",
  "workspaceId": "987xyz654abc321mno987pqr654stu",
  "phoneNumber": "+12345678901",
  "country": "US",
  "type": "local",
  "status": "released",
  "recordingEnabled": true,
  "pathwayId": "xyz123abc456",
  "monthlyPrice": 19.99,
  "expiresAt": "2025-12-31T11:59:59.999Z",
  "transferEnabled": true,
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-10T15:30:00.000Z",
  "agentId": "789xyz123abc456def",
  "flowType": "outbound",
  "messagePathwayId": "123abc456xyz789",
  "omniFlowAgentId": "omni123flow456agent789"
}
```
</ResponseExample>

---

## Get a Specific Call History

*Retrieve detailed information about a specific call history entry.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="callHistoryId" type="string" required>
  The unique identifier of the call record in the database.
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the call history record.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace associated with this call history.
</ResponseField>

<ResponseField name="agentId" type="string">
  The identifier of the agent involved in the call.
</ResponseField>

<ResponseField name="callFlowId" type="string">
  The identifier of the call flow used during the call.
</ResponseField>

<ResponseField name="roomName" type="string">
  The virtual room name where the call took place.
</ResponseField>

<ResponseField name="direction" type="string">
  The direction of the call (e.g., "inbound" or "outbound").
</ResponseField>

<ResponseField name="fromPhoneNumber" type="string">
  The phone number from which the call originated.
</ResponseField>

<ResponseField name="toPhoneNumber" type="string">
  The phone number to which the call was made.
</ResponseField>

<ResponseField name="status" type="string">
  The final status of the call (e.g., "completed", "failed", "ongoing").
</ResponseField>

<ResponseField name="startTime" type="number">
  The start time of the call as a Unix timestamp.
</ResponseField>

<ResponseField name="endTime" type="number">
  The end time of the call as a Unix timestamp.
</ResponseField>

<ResponseField name="cost" type="object">
  Details of the costs incurred during the call.
  <ResponseField name="customer_charge" type="number">
    The charge to the customer for the call.
  </ResponseField>
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional metadata associated with the call.
</ResponseField>

<ResponseField name="functionCalls" type="array">
  An array detailing any functional calls made during the interaction.
</ResponseField>

<ResponseField name="summary" type="string">
  A brief summary of the call.
</ResponseField>

<ResponseField name="analyzedData" type="object">
  Analyzed data from the call that may include additional fields.
  <ResponseField name="additional_field" type="string">
    Additional details from the analyzed data.
  </ResponseField>
</ResponseField>

<ResponseField name="createdAt" type="string">
    Timestamp when the call history was created.
</ResponseField>
<ResponseField name="updatedAt" type="string">
  Timestamp when the call history was last updated.
</ResponseField>

<ResponseExample>
```json
{
  "_id": "1234567890abcdef",
  "workspaceId": "abcdef1234567890",
  "agentId": "abcdef1234567890",
  "callFlowId": "abcdef1234567890",
  "roomName": "web-1234abcd",
  "direction": "outbound",
  "fromPhoneNumber": "+10000000000",
  "toPhoneNumber": "+10000000001",
  "status": "completed",
  "startTime": 1680000000,
  "endTime": 1680000300,
  "cost": {
    "customer_charge": 0.10
  },
  "metadata": {},
  "functionCalls": [],
  "summary": "Generic conversation summary about customer engagement.",
  "analyzedData": {
    "additional_field": "generic details"
  },
  "createdAt": "2025-01-01T10:00:00Z",
  "updatedAt": "2025-01-01T10:05:00Z"
}
```
</ResponseExample>

---

## List Call Histories

*Retrieve a list of call history records in your workspace.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Query Parameters

<ParamField query="page" type="integer">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField query="limit" type="integer">
  Number of records per page. Defaults to `10`.
</ParamField>

<ParamField query="agentId" type="string">
  Filter call histories by agent ID.
</ParamField>

<ParamField query="pathwayId" type="string">
  Filter call histories by call flow (pathway) ID.
</ParamField>

<ParamField query="batchId" type="string">
  Filter call histories belonging to a specific batch call.
</ParamField>

<ParamField query="status" type="string">
  Filter by call status (e.g. `completed`, `failed`, `in-progress`).
</ParamField>

<ParamField query="direction" type="string">
  Filter by call direction: `inbound` or `outbound`.
</ParamField>

<ParamField query="callType" type="string">
  Filter by call type: `sip` or `web`.
</ParamField>

<ParamField query="search" type="string">
  Free-text search across phone numbers / call metadata.
</ParamField>

<ParamField query="callIds" type="string">
  JSON-stringified array of specific call IDs to fetch (e.g. `["abc","def"]`).
</ParamField>

<ParamField query="dateRange" type="string">
  JSON-stringified object with `from` and `to` ISO timestamps (e.g. `{"from":"2024-01-01","to":"2024-01-31"}`).
</ParamField>

<ParamField query="postAnalysis" type="string">
  JSON-stringified filter object for post-call analysis fields.
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the call history record.
</ResponseField>

<ResponseField name="timestamp" type="number">
  The Unix timestamp indicating when the call was made.
</ResponseField>

<ResponseField name="callId" type="string">
  A unique identifier associated with the specific call.
</ResponseField>

<ResponseField name="fromPhoneNumber" type="string">
  The phone number from which the call originated.
</ResponseField>

<ResponseField name="toPhoneNumber" type="string">
  The phone number to which the call was directed.
</ResponseField>

<ResponseField name="direction" type="string">
  The direction of the call, typically "inbound", "outbound", or "bidirectional".
</ResponseField>

<ResponseField name="agent" type="string">
  The name or identifier of the agent involved in the call.
</ResponseField>

<ResponseField name="status" type="string">
  The status of the call, such as "active", "completed", or other relevant statuses.
</ResponseField>

<ResponseField name="callFlowName" type="string">
  The name of the call flow  used during the call.
</ResponseField>

<ResponseField name="cost" type="number">
  The cost incurred for the call, if applicable.
</ResponseField>

<ResponseField name="recordingUrl" type="string" optional="true">
  A URL pointing to the recorded audio of the call, if available.
</ResponseField>

<ResponseField name="summary" type="string">
  A brief summary or overview of the call.
</ResponseField>

<ResponseField name="analyzedData" type="object">
  An object containing additional analyzed data from the call, such as flags for voicemail detection or other specific features.
  <ResponseField name="answered_by_voicemail" type="boolean" optional="true">
    Indicates whether the call was answered by a voicemail system.
  </ResponseField>
</ResponseField>

<ResponseField name="variables" type="object">
  Any variables that were used or modified during the call.
</ResponseField>

<ResponseField name="transcript" type="array">
  An array containing elements of the call transcript, if available.
</ResponseField>

<ResponseExample>
```json
[
  {
    "_id": "00000000bf7ca4a7c69e0000",
    "timestamp": 1737062894.9754236,
    "callId": "00000000013bd867b55ca000-00t00imaqj",
    "fromPhoneNumber": "+00000000000",
    "toPhoneNumber": "+00000000000",
    "direction": "bidirectional",
    "agent": "SampleAgent",
    "status": "active",
    "callFlowName": "Example Call Flow",
    "cost": 0,
    "recordingUrl": null,
    "summary": "Call summary here",
    "analyzedData": {},
    "variables": {},
    "transcript": []
  },
  {
    "_id": "00000000cbddbe9988450000",
    "timestamp": 1737061847.891025,
    "callId": "00000000013bd867b55ca000-00pk0su000",
    "fromPhoneNumber": "+00000000000",
    "toPhoneNumber": "+00000000000",
    "direction": "bidirectional",
    "duration": 0,
    "agent": "SampleAgent",
    "status": "completed",
    "callFlowName": "Example Call Flow",
    "cost": 0,
    "recordingUrl": null,
    "summary": "Call summary here",
    "analyzedData": {
      "answered_by_voicemail": false
    },
    "variables": {},
    "transcript": []
  }
]
```
</ResponseExample>

---

## Get Call History Metrics

*Retrieve aggregated metrics and analytics for call history records in your workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Query Parameters

<ParamField query="agentId" type="string">
Filter metrics by a specific agent ID.
</ParamField>

<ParamField query="status" type="string">
Filter by call status (e.g., "completed", "failed", "no-answer").
</ParamField>

<ParamField query="direction" type="string">
Filter by call direction ("inbound", "outbound", "bidirectional").
</ParamField>

<ParamField query="pathwayId" type="string">
Filter by call flow ID.
</ParamField>

<ParamField query="dateRange" type="string">
JSON string with startDate and endDate in ISO format. Example: `{"startDate":"2024-01-01","endDate":"2024-01-31"}`
</ParamField>

<ParamField query="callType" type="string">
Filter by call type: "sip" or "web".
</ParamField>

## Response Fields

<ResponseField name="totalCalls" type="number">
Total number of calls matching the filters.
</ResponseField>

<ResponseField name="completedCalls" type="number">
Number of completed calls.
</ResponseField>

<ResponseField name="failedCalls" type="number">
Number of failed calls.
</ResponseField>

<ResponseField name="averageDuration" type="number">
Average call duration in seconds.
</ResponseField>

<ResponseField name="totalCost" type="number">
Total cost of all calls.
</ResponseField>

<ResponseExample>
```json
{
  "totalCalls": 150,
  "completedCalls": 120,
  "failedCalls": 10,
  "averageDuration": 180,
  "totalCost": 45.50
}
```
</ResponseExample>

---

## Get Call Phonebook

*Retrieve the most frequently called phone numbers in your workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Response Fields

<ResponseField name="data" type="array">
Array of phone number objects ordered by frequency.

<ResponseField name="toPhoneNumber" type="string">
The phone number in E.164 format.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
[
  { "toPhoneNumber": "+14155551234" },
  { "toPhoneNumber": "+14155555678" },
  { "toPhoneNumber": "+14155559012" }
]
```
</ResponseExample>

---

## Connect a Web Call

*Initiate a live web-based call session with an AI agent.*

Initiate a web call that runs entirely via WebRTC in the browser (no phone number required). The agent can interact via voice.  

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>


### Request Body

<ParamField body="agentId" type="string" required>
  The ID of the agent that will handle this web call.
</ParamField>

<ParamField body="mode" type="string">
  The mode of the call. Defaults to "voice".
</ParamField>

<ResponseExample>
```json
{
  "status": "success",
  "callId": "call1234",
  "roomName": "web-genericAgent-call1234",
  "token": "<REDACTED_JWT_TOKEN>",
  "agent": {
    "id": "agent12345678",
    "name": "Generic Agent",
    "model": "llm-mini",
    "voice": {
      "provider": "genericVoiceProvider",
      "voiceId": "standard",
      "language": "en"
    }
  }
}
```
</ResponseExample>

---

## Disconnect a Web Call

*End an ongoing web-based call session.*

End an active web-based call session. This API notifies the server that the user is done.

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>


### Request Body

<ParamField body="roomName" type="string" required>
  The room name for the ongoing LiveKit session.
</ParamField>

<ResponseExample>
```json
{
  "status": "success",
  "message": "Session ended successfully"
}
```
</ResponseExample>

---

## Create Call Flow

*Create a new call flow with full settings.*

### Headers  
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  A friendly name for this call flow (e.g., "Customer Support Flow").
</ParamField>

<ParamField body="direction" type="string" required>
  Direction of the flow. Possible values: "outbound", "bidirectional".
</ParamField>

<ParamField body="description" type="string">
  Description of the call flow (e.g. "Handles inbound support calls").
</ParamField>

<ParamField body="agent" type="string">
  ID of the agent to associate with this flow. If provided, the system looks for a pending phone number for that agent and activates it.
</ParamField>

<ParamField body="promptType" default="simple" type="string" required>
  Only "simple" type of prompt configuration is allowed now.
</ParamField>

<ParamField body="folderId" type="string">
  ID of the folder to organize this call flow.
</ParamField>

<ParamField body="isGlobal" type="boolean">
  Whether this is a global call flow. Only specific workspaces can create global flows.
</ParamField>

<ParamField body="isPreConfigured" type="boolean">
  Whether this call flow is pre-configured. Defaults to false.
</ParamField>

<ParamField body="preConfiguredWorkspaceId" type="string">
  Workspace ID for pre-configured flows.
</ParamField>

<ParamField body="welcomeMessage" type="string">
  Welcome message type. Possible values: "user_initiated", "ai_dynamic", "ai_custom". Defaults to "user_initiated".
</ParamField>

<ParamField body="customWelcomeMessage" type="string">
  Custom welcome message text when welcomeMessage is set to "ai_custom" only.
</ParamField>

<ParamField body="flowData" type="object">
  Flow-based configuration using a node/edge approach for complex call routing.

  <Expandable title="flowData">
    <ParamField body="nodes" type="array">
      Array of node objects, each representing a point in the call routing process. Each node object may include properties like `id`, `type`, and `data` for custom configurations.
    </ParamField>
    <ParamField body="edges" type="array">
      Array of edge objects, connecting the nodes defined in the `nodes` array. Each edge object can specify the source and target nodes, along with additional routing logic.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="prompt" type="string">
  A system or initial prompt for the flow. This will be used to create the first prompt version.
</ParamField>


<ParamField body="isActive" type="boolean">
  Whether the flow is currently active. Defaults to true.
</ParamField>

<ParamField body="agentWebhookUrl" type="string">
  Webhook URL for agent-related events.
</ParamField>

<ParamField body="inboundWebhookUrl" type="string">
  Webhook URL for inbound call events.
</ParamField>

<ParamField body="dynamicVariableCollections" type="array">
  Array of dynamic variable collections for the call flow.
  
  <Expandable title="dynamicVariableCollections">
    <ParamField body="id" type="string" required>
      Unique identifier for the variable collection.
    </ParamField>
    <ParamField body="name" type="string" required>
      Name of the variable collection.
    </ParamField>
    <ParamField body="variables" type="array">
      Array of key-value pairs for variables.
      <ParamField body="key" type="string">
        Variable key name.
      </ParamField>
      <ParamField body="value" type="string">
        Variable value.
      </ParamField>
    </ParamField>
    <ParamField body="isDefault" type="boolean">
      Whether this is the default variable collection. Defaults to false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="webhooks" type="array">
  Array of webhook configurations for the call flow.
  
  <Expandable title="webhooks">
    <ParamField body="name" type="string" required>
      Name of the webhook.
    </ParamField>
    <ParamField body="url" type="string" required>
      Webhook URL endpoint.
    </ParamField>
    <ParamField body="method" type="string">
      HTTP method. Possible values: "GET", "POST", "PUT", "DELETE". Defaults to "POST".
    </ParamField>
    <ParamField body="headers" type="object">
      Key-value pairs for HTTP headers.
    </ParamField>
    <ParamField body="body" type="string">
      Request body content.
    </ParamField>
    <ParamField body="description" type="string">
      Description of the webhook purpose.
    </ParamField>
    <ParamField body="variablesforcallflow" type="array">
      Variables available for call flow.
      <ParamField body="name" type="string">
        Variable name.
      </ParamField>
      <ParamField body="description" type="string">
        Variable description.
      </ParamField>
    </ParamField>
    <ParamField body="responseVariables" type="array">
      Variables extracted from webhook responses.
      <ParamField body="name" type="string">
        Response variable name.
      </ParamField>
      <ParamField body="path" type="string">
        JSON path to extract the variable value.
      </ParamField>
      <ParamField body="description" type="string">
        Response variable description.
      </ParamField>
    </ParamField>
    <ParamField body="isTesting" type="boolean">
      Whether the webhook is in testing mode.
    </ParamField>
    <ParamField body="textToSpeak" type="string">
      Text to be spoken when webhook is triggered.
    </ParamField>
    <ParamField body="testResponse" type="string">
      Mock response for testing purposes.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="settings" type="object">
  Main configuration object for the call flow.

  <Expandable title="settings">
    <ParamField body="welcomeMessage" type="string">
      Welcome message type. Possible values: "user_initiated", "ai_dynamic", "ai_custom".
    </ParamField>
    <ParamField body="customWelcomeMessage" type="string">
      Custom welcome message text.
    </ParamField>
    <ParamField body="enableHumanLikeVoiceAndTone" type="boolean">
      Enable human-like voice and tone. Defaults to false.
    </ParamField>
    <ParamField body="welcomeMessageDelay" type="number">
      Delay in seconds before welcome message. Defaults to 0.
    </ParamField>
    <ParamField body="webhooks" type="object">
      Webhook URLs for different events.
      <ParamField body="agent" type="string">
        Agent webhook URL.
      </ParamField>
      <ParamField body="inbound" type="string">
        Inbound webhook URL.
      </ParamField>
    </ParamField>
    <ParamField body="customerLocation" type="string">
      Customer location for the call flow. Defaults to "new york".
    </ParamField>
    <ParamField body="transfers" type="array">
      Array of transfer configurations.
    </ParamField>
    <ParamField body="knowledgeBases" type="array">
      Array of knowledge base IDs to associate with this call flow.
    </ParamField>
    <ParamField body="utilizePriorCallsContext" type="boolean">
      Whether to utilize context from prior calls. Defaults to false.
    </ParamField>
    <ParamField body="callSettings" type="object">
      Call-specific settings.
      <ParamField body="trilletVoiceGuard" type="boolean">
        Enable Trillet voice guard. Defaults to true.
      </ParamField>
      <ParamField body="reminderMessages" type="array">
        Array of reminder message strings.
      </ParamField>
    </ParamField>
    <ParamField body="security" type="object">
      Security configuration settings.
      <ParamField body="securityOptOut" type="boolean">
        Whether to opt out of security features (affects HIPAA compliance).
      </ParamField>
      <ParamField body="publicAccess" type="boolean">
        Whether to allow public access to the call flow.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the newly created call flow.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the call flow has been created.
</ResponseField>

<ResponseField name="folderId" type="string">
  The identifier of the folder where the call flow is organized.
</ResponseField>

<ResponseField name="isGlobal" type="boolean">
  Whether this is a global call flow.
</ResponseField>

<ResponseField name="isPreConfigured" type="boolean">
  Whether this call flow is pre-configured.
</ResponseField>

<ResponseField name="preConfiguredWorkspaceId" type="string">
  Workspace ID for pre-configured flows.
</ResponseField>

<ResponseField name="name" type="string">
  The name given to the call flow.
</ResponseField>

<ResponseField name="direction" type="string">
  The direction configuration of the call flow; can be "inbound", "outbound", or "bidirectional".
</ResponseField>

<ResponseField name="description" type="string">
  A description of what the call flow is designed to handle.
</ResponseField>

<ResponseField name="agent" type="string">
  The identifier of the agent associated with this call flow.
</ResponseField>

<ResponseField name="promptType" default="simple" type="string">
  Only "simple" prompt types allowed now.
</ResponseField>

<ResponseField name="welcomeMessage" type="string">
  Welcome message type configuration.
</ResponseField>

<ResponseField name="customWelcomeMessage" type="string">
  Custom welcome message text if configured.
</ResponseField>

<ResponseField name="flowData" type="object">
  The configuration of nodes and edges that define the call routing logic within the flow.
  <ResponseField name="nodes" type="array">
    Detailed configuration of the nodes within the call flow.
  </ResponseField>
  <ResponseField name="edges" type="array">
    Configurations of the edges connecting nodes within the call flow.
  </ResponseField>
</ResponseField>

<ResponseField name="prompt" type="string">
  The initial or system prompt used in the call flow.
</ResponseField>

<ResponseField name="currentPromptId" type="string">
  ID of the current active prompt version.
</ResponseField>

<ResponseField name="promptVersions" type="array">
  Array of prompt versions with their metadata.
  <ResponseField name="_id" type="string">
    Unique identifier for the prompt version.
  </ResponseField>
  <ResponseField name="name" type="string">
    Name of the prompt version.
  </ResponseField>
  <ResponseField name="prompt" type="string">
    Prompt content for this version.
  </ResponseField>
  <ResponseField name="metadata" type="object">
    Additional metadata including notes.
  </ResponseField>
</ResponseField>

<ResponseField name="gemini_prompt" type="string">
  Sanitized version of the prompt for Gemini processing.
</ResponseField>

<ResponseField name="isActive" type="boolean">
  Indicates whether the call flow is currently active or inactive.
</ResponseField>

<ResponseField name="agentWebhookUrl" type="string">
  Webhook URL for agent-related events.
</ResponseField>

<ResponseField name="inboundWebhookUrl" type="string">
  Webhook URL for inbound call events.
</ResponseField>

<ResponseField name="dynamicVariableCollections" type="array">
  Array of dynamic variable collections configured for the call flow.
</ResponseField>

<ResponseField name="locations" type="array">
  Array of location objects for visual flow positioning.
</ResponseField>

<ResponseField name="webhooks" type="array">
  Array of configured webhooks with their complete configuration.
</ResponseField>

<ResponseField name="settings" type="object">
  Configuration settings for various aspects of the call flow, including welcome messages, webhooks, knowledge bases, call settings, and security.
  <ResponseField name="security" type="object">
    Security settings with processed values.
    <ResponseField name="hipaaCompliance" type="boolean">
      HIPAA compliance status (processed from securityOptOut).
    </ResponseField>
    <ResponseField name="publicAccess" type="boolean">
      Public access configuration.
    </ResponseField>
  </ResponseField>
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the call flow was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the call flow was last updated.
</ResponseField>


<ResponseExample>
```json
{
  "_id": "676b8e123456789012345678",
  "workspaceId": "6764d172953253138a3a70f4",
  "folderId": null,
  "isGlobal": false,
  "isPreConfigured": false,
  "preConfiguredWorkspaceId": null,
  "name": "Customer Support Flow",
  "direction": "inbound",
  "description": "Handles inbound support calls",
  "agent": "676b8e123456789012345679",
  "promptType": "simple",
  "welcomeMessage": "user_initiated",
  "customWelcomeMessage": "",
  "flowData": {
    "nodes": [
      {
        "id": "node1",
        "type": "start",
        "data": {
          "prompt": "Welcome to our support line. How can I help you?"
        }
      }
    ],
    "edges": []
  },
  "prompt": "Keep the conversation short and friendly.",
  "currentPromptId": "676b8e123456789012345680",
  "promptVersions": [
    {
      "_id": "676b8e123456789012345680",
      "name": "Prompt Version - 1/15/2025, 3:00:00 PM",
      "prompt": "Keep the conversation short and friendly.",
      "metadata": {
        "notes": ""
      },
      "createdAt": "2025-01-15T15:00:00.000Z",
      "updatedAt": "2025-01-15T15:00:00.000Z"
    }
  ],
  "gemini_prompt": "Keep the conversation short and friendly.",
  "startNodeId": null,
  "isActive": true,
  "agentWebhookUrl": "",
  "inboundWebhookUrl": "",
  "dynamicVariableCollections": [],
  "locations": [],
  "webhooks": [],
  "settings": {
    "welcomeMessage": "user_initiated",
    "customWelcomeMessage": "",
    "enableHumanLikeVoiceAndTone": false,
    "welcomeMessageDelay": 0,
    "webhooks": {
      "agent": "",
      "inbound": ""
    },
    "customerLocation": "new york",
    "transfers": [],
    "knowledgeBases": [],
    "utilizePriorCallsContext": false,
    "callSettings": {
      "trilletVoiceGuard": true,
      "reminderMessages": []
    },
    "security": {
      "hipaaCompliance": false,
      "publicAccess": false
    }
  },
  "createdAt": "2025-01-15T15:00:00.000Z",
  "updatedAt": "2025-01-15T15:00:00.000Z"
}
```
</ResponseExample>

---

## Delete Call Flow

*Permanently remove a call flow.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique ID of the call flow to delete.
</ParamField>

<ResponseExample>
```json 
HTTP/1.1 204 No Content 
```
</ResponseExample>

---

## Get Call Flow

*Retrieve a specific call flow by its ID.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique ID of the call flow.
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the call flow.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the call flow is configured.
</ResponseField>

<ResponseField name="name" type="string">
  The name assigned to the call flow.
</ResponseField>

<ResponseField name="direction" type="string">
  Indicates the direction of the call flow, such as "inbound".
</ResponseField>

<ResponseField name="description" type="string">
  A brief description of what the call flow is designed to handle.
</ResponseField>

<ResponseField name="agent" type="string">
  The ID of the agent associated with this call flow.
</ResponseField>

<ResponseField name="promptType" type="string">
  The type of prompt used in the call flow, such as "simple".
</ResponseField>

<ResponseField name="flowData" type="object">
  Contains the configuration of nodes and edges defining the call routing logic.
  <ResponseField name="nodes" type="array">
    An array detailing each node in the call flow.
  </ResponseField>
  <ResponseField name="edges" type="array">
    An array detailing the edges connecting the nodes.
  </ResponseField>
</ResponseField>

<ResponseField name="prompt" type="string">
  The initial or system prompt that is presented in the call flow.
</ResponseField>

<ResponseField name="isActive" type="boolean">
  Indicates whether the call flow is currently active.
</ResponseField>

<ResponseField name="settings" type="object">
  The configuration settings for the call flow, including details on knowledge bases, response settings, security measures, and call settings.
  <ResponseField name="knowledgeBases" type="array">
    An array of references to knowledge bases included in the call flow.
  </ResponseField>
  <ResponseField name="responseSettings" type="object">
    Settings related to response timing within the call flow.
    <ResponseField name="delay" type="number">
      The delay before a response is issued, measured in seconds.
    </ResponseField>
  </ResponseField>
  <ResponseField name="security" type="object">
    Security settings relevant to the call flow.
    <ResponseField name="hipaaCompliance" type="boolean">
      Indicates whether HIPAA compliance is enabled.
    </ResponseField>
  </ResponseField>
  <ResponseField name="callSetting" type="object">
    Call-related settings for managing the call duration and handling silence.
    <ResponseField name="maxCallDuration" type="number">
      The maximum duration for the call, measured in seconds.
    </ResponseField>
    <ResponseField name="endCallOnSilence" type="number">
      The duration of silence that triggers the end of the call, measured in seconds.
    </ResponseField>
  </ResponseField>
</ResponseField>

<ResponseField name="createdAt" type="string">
    Timestamp when the call flow was created.
</ResponseField>
<ResponseField name="updatedAt" type="string">
    Timestamp when the call flow was last updated.
</ResponseField>

<ResponseExample>

```json
{
  "_id": "exampleId",
  "workspaceId": "workspacePlaceholder",
  "name": "Customer Support Flow",
  "direction": "inbound",
  "description": "Handles inbound support calls",
  "agent": "agentPlaceholder",
  "promptType": "simple",
  "flowData": {
    "nodes": [],
    "edges": []
  },
  "prompt": "Keep the conversation short and friendly.",
  "isActive": true,
  "settings": {
    "knowledgeBases": [],
    "responseSettings": { "delay": 0 },
    "security": { "hipaaCompliance": false },
    "callSetting": { "maxCallDuration": 600, "endCallOnSilence": 10 }
  },
  "createdAt": "2025-01-03T11:00:00Z",
  "updatedAt": "2025-01-03T11:10:00Z"
}
```

</ResponseExample>

---

## Delete Knowledge Base File

*Delete a knowledge base file associated with a specific call flow.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the call flow from which the knowledge base file will
  be deleted.
</ParamField>

<ParamField path="fileKey" type="string" required>
  The key of the knowledge base file to be deleted. The file key is typically a
  unique identifier or filename used in the storage system.
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the call flow from which the knowledge base file was deleted.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace associated with the call flow.
</ResponseField>

<ResponseField name="settings" type="object">
  Contains updated settings for the call flow following the deletion of the knowledge base file.
  <ResponseField name="knowledgeBaseFiles" type="array">
    An array representing the remaining knowledge base files after the deletion. Each element in the array is an object that includes details such as the file name, type, and any other relevant metadata.
  </ResponseField>
</ResponseField>

<ResponseExample>
  ```json
  {
    "_id": "callFlowId",
    "workspaceId": "workspaceIdExample",
    "settings": {
      "knowledgeBaseFiles": [
        // Remaining files after deletion
      ]
    }
  }
```
</ResponseExample>

---

## Upload Knowledge Base File

*Upload a knowledge base file to a specific call flow.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the call flow to which the knowledge base file will
  be uploaded.
</ParamField>

### Request Body

<ParamField body="file" type="file" required>
  The knowledge base file to upload. Accepted file formats are PDF (.pdf), plain
  text (.txt), Word document (.docx), and Markdown (.md).
  <Note> 
    Only one file can be uploaded per request.
  </Note>
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the call flow to which the knowledge base file has been uploaded.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace associated with the call flow.
</ResponseField>

<ResponseField name="settings" type="object">
  Contains the updated settings for the call flow following the file upload.
  <ResponseField name="knowledgeBaseFiles" type="array">
    An array of objects representing the knowledge base files associated with the call flow. Each object in this array provides details about the uploaded files, including:
    <ResponseField name="filename" type="string">
      The name of the file as stored in the system.
    </ResponseField>
    <ResponseField name="key" type="string">
      A unique key or identifier used internally to reference the file.
    </ResponseField>
    <ResponseField name="url" type="string">
      A URL where the uploaded file can be accessed or downloaded.
    </ResponseField>
  </ResponseField>
</ResponseField>

<ResponseExample>
```json
  {
    "_id": "flowId",
    "workspaceId": "workspaceIdExample",
    "settings": {
      "knowledgeBaseFiles": [
        {
          "filename": "exampleFile.pdf",
          "key": "s3FileKey",
          "url": "https://example.com/file.pdf"
        }
      ]
    }
  }
```
</ResponseExample>

---

## List Call Flows

*Retrieve a list of all call flows in the workspace.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Response Fields

Each object in the response array represents a call flow within the workspace, containing the following fields:

<ResponseField name="_id" type="string">
  The unique identifier for the call flow.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the call flow is configured.
</ResponseField>

<ResponseField name="name" type="string">
  The name assigned to the call flow.
</ResponseField>

<ResponseField name="direction" type="string">
  Indicates the direction of the call flow, such as "inbound" or "bidirectional".
</ResponseField>

<ResponseField name="agent" type="string">
  The identifier of the agent associated with the call flow.
</ResponseField>

<ResponseField name="isActive" type="boolean">
  A boolean indicating whether the call flow is currently active.
</ResponseField>

<ResponseField name="promptType" type="string">
  The type of prompt used in the call flow, either "simple" or "flow".
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the call flow was updated.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the call flow was last updated.
</ResponseField>


<ResponseExample>

```json
[
  {
    "_id": "flowId1",
    "workspaceId": "workspaceIdExample1",
    "name": "Customer Support Flow",
    "direction": "inbound",
    "agent": "agentIdExample1",
    "isActive": true,
    "promptType": "simple",
    "createdAt": "2025-01-02T09:00:00Z",
    "updatedAt": "2025-01-02T09:30:00Z"
  },
  {
    "_id": "flowId2",
    "workspaceId": "workspaceIdExample2",
    "name": "Sales Inquiry Flow",
    "direction": "bidirectional",
    "agent": "agentIdExample2",
    "isActive": false,
    "promptType": "flow",
    "createdAt": "2025-01-05T09:00:00Z",
    "updatedAt": "2025-01-06T12:00:00Z"
  }
]
```

</ResponseExample>

---

## Update Call Flow

*Update an existing call flow.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
The unique ID of the call flow to update.
</ParamField>

## Request Body

<ParamField body="name" type="string">
New name for the flow.
</ParamField>

<ParamField body="description" type="string">
Updated description for the call flow (e.g., "Updated description for inbound calls").
</ParamField>

<ParamField body="direction" type="string" enum={['outbound', 'bidirectional']}>
The direction of the call flow. 'outbound' or 'bidirectional'
</ParamField>

<ParamField body="isActive" type="boolean">
Whether the call flow is currently active.
</ParamField>

<ParamField body="isGlobal" type="boolean">
Whether this is a global call flow (requires special permissions).
</ParamField>

<ParamField body="promptType" type="string" required>
The type of prompt used in the call flow "simple".
</ParamField>

<ParamField body="prompt" type="string">
The primary prompt for user interaction (used when promptType is 'simple').
</ParamField>

<ParamField body="welcomeMessage" type="string" enum={['user_initiated', 'ai_dynamic', 'ai_custom']} default="user_initiated">
Type of welcome message for the call flow. Possible values: “user_initiated”, “ai_dynamic”, “ai_custom”. Defaults to “user_initiated”.
</ParamField>

<ParamField body="customWelcomeMessage" type="string">
Custom welcome message text (used when welcomeMessage is 'ai_custom').
</ParamField>

<ParamField body="dynamicVariableCollections" type="array">
Collections of dynamic variables for the call flow.
<Expandable title="dynamicVariableCollections">
  <ParamField body="id" type="string" required>
    Unique identifier for the variable collection.
  </ParamField>
  <ParamField body="name" type="string" required>
    Name of the variable collection.
  </ParamField>
  <ParamField body="isDefault" type="boolean" default="false">
    Whether this is the default variable collection.
  </ParamField>
  <ParamField body="variables" type="array">
    Array of key-value pairs.
    <Expandable title="variables">
      <ParamField body="key" type="string">
        Variable key name.
      </ParamField>
      <ParamField body="value" type="string">
        Variable value.
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>
</ParamField>

<ParamField body="settings" type="object">
Configuration settings for the call flow.
<Expandable title="settings">
  <ParamField body="enableHumanLikeVoiceAndTone" type="boolean">
    Whether to enable human-like voice and tone.
  </ParamField>
  <ParamField body="welcomeMessageDelay" type="number">
    Delay in seconds before playing the welcome message.
  </ParamField>
  <ParamField body="customerLocation" type="string">
    Default customer location (e.g., "new york").
  </ParamField>
  <ParamField body="utilizePriorCallsContext" type="boolean">
    Whether to use context from previous calls.
  </ParamField>

  <ParamField body="responseSettings" type="object">
    <Expandable title="responseSettings">
      <ParamField body="delay" type="number">
        Delay (in seconds) before responding.
      </ParamField>
      <ParamField body="workingHours" type="object">
        <Expandable title="workingHours">
          <ParamField body="enabled" type="boolean">
            Whether working hours logic is enabled.
          </ParamField>
          <ParamField body="start" type="string">
            Start time for working hours, e.g., "08:00".
          </ParamField>
          <ParamField body="end" type="string">
            End time for working hours, e.g., "20:00".
          </ParamField>
          <ParamField body="timezone" type="string">
            Timezone for working hours, e.g., "America/New_York".
          </ParamField>
          <ParamField body="outOfHoursMessage" type="string">
            Automated reply for out-of-hours calls.
          </ParamField>
        </Expandable>
      </ParamField>
    </Expandable>
  </ParamField>

  <ParamField body="security" type="object">
    <Expandable title="security">
      <ParamField body="hipaaCompliance" type="boolean">
        Whether HIPAA compliance is required. When enabled, automatically disables call recording.
      </ParamField>
      <ParamField body="publicAccess" type="boolean">
        Whether public access is allowed.
      </ParamField>
    </Expandable>
  </ParamField>

  <ParamField body="callSetting" type="object">
    <Expandable title="callSetting">
      <ParamField body="maxCallDuration" type="number">
        Maximum call duration (in seconds).
      </ParamField>
      <ParamField body="endCallOnSilence" type="number">
        Timeout (in seconds) for ending a call if no audio is detected.
      </ParamField>
      <ParamField body="trilletVoiceGuard" type="boolean">
        Whether to enable Trillet voice guard protection.
      </ParamField>
      <ParamField body="reminderMessages" type="array">
        Array of reminder messages to be played during calls.
      </ParamField>
    </Expandable>
  </ParamField>

  <ParamField body="knowledgeBaseFiles" type="array">
    Array of knowledge base files associated with the call flow.
    <Expandable title="knowledgeBaseFiles">
      <ParamField body="filename" type="string">
        Name of the knowledge base file.
      </ParamField>
      <ParamField body="key" type="string">
        Storage key for the file.
      </ParamField>
      <ParamField body="url" type="string">
        URL to access the file.
      </ParamField>
    </Expandable>
  </ParamField>

  <ParamField body="knowledgeBases" type="array">
    Array of knowledge base IDs referenced by the call flow.
  </ParamField>

  <ParamField body="transfers" type="array">
    Array of transfer configurations for the call flow.
  </ParamField>

</Expandable>
</ParamField>

<ParamField body="webhooks" type="array">
List of webhooks to be added to the call flow. A new webhook will be created for each entry in the array, regardless of the name or if it already exists.
<Expandable title="webhooks">
  <ParamField body="name" type="string" required>
    The name of the webhook (e.g., "Booking").
  </ParamField>
  <ParamField body="description" type="string">
    A brief description of what this webhook does (e.g., "Booking request webhook").
  </ParamField>
  <ParamField body="url" type="string" required>
    The URL to which the webhook will send data (e.g., "https://example.com/webhook/agent").
  </ParamField>
  <ParamField body="method" type="string" enum={['GET', 'POST', 'PUT', 'DELETE']} default="POST">
    HTTP method for the webhook request.
  </ParamField>
  <ParamField body="headers" type="object">
    Headers to be included in the webhook request.
  </ParamField>
  <ParamField body="body" type="string">
    The webhook request body. Can include variable placeholders.
  </ParamField>
  <ParamField body="variables" type="array">
    A list of variables used in the webhook body for dynamic content generation.
    <Expandable title="variables">
      <ParamField body="name" type="string" required>
        The name of the variable.
      </ParamField>
      <ParamField body="description" type="string" required>
        A description of the variable.
      </ParamField>
    </Expandable>
  </ParamField>
  <ParamField body="responseVariables" type="array">
    Variables to extract from the webhook response.
    <Expandable title="responseVariables">
      <ParamField body="name" type="string">
        Name of the response variable.
      </ParamField>
      <ParamField body="path" type="string">
        JSON path to extract the value from the response.
      </ParamField>
      <ParamField body="description" type="string">
        Description of the response variable.
      </ParamField>
    </Expandable>
  </ParamField>
  <ParamField body="isTesting" type="boolean">
    Whether this webhook is in testing mode.
  </ParamField>
  <ParamField body="testResponse" type="string">
    Mock response for testing purposes.
  </ParamField>
  <ParamField body="textToSpeak" type="string">
    Text to be spoken when this webhook is triggered.
  </ParamField>
</Expandable>
</ParamField>

<Note>
These `endCallOnSilence` and `maxCallDuration` settings are recommended to be sent for optimal API performance, though they are not strictly required.
</Note>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the newly created call flow.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the call flow has been created.
</ResponseField>

<ResponseField name="folderId" type="string">
  The identifier of the folder where the call flow is organized.
</ResponseField>

<ResponseField name="isGlobal" type="boolean">
  Whether this is a global call flow.
</ResponseField>

<ResponseField name="isPreConfigured" type="boolean">
  Whether this call flow is pre-configured.
</ResponseField>

<ResponseField name="preConfiguredWorkspaceId" type="string">
  Workspace ID for pre-configured flows.
</ResponseField>

<ResponseField name="name" type="string">
  The name given to the call flow.
</ResponseField>

<ResponseField name="direction" type="string">
  The direction configuration of the call flow; can be "inbound", "outbound", or "bidirectional".
</ResponseField>

<ResponseField name="description" type="string">
  A description of what the call flow is designed to handle.
</ResponseField>

<ResponseField name="agent" type="string">
  The identifier of the agent associated with this call flow.
</ResponseField>

<ResponseField name="promptType" type="string">
  Indicates whether the call flow uses "simple" or "flow" based configuration.
</ResponseField>

<ResponseField name="welcomeMessage" type="string">
  Welcome message type configuration.
</ResponseField>

<ResponseField name="customWelcomeMessage" type="string">
  Custom welcome message text if configured.
</ResponseField>

<ResponseField name="flowData" type="object">
  The configuration of nodes and edges that define the call routing logic within the flow.
  <ResponseField name="nodes" type="array">
    Detailed configuration of the nodes within the call flow.
  </ResponseField>
  <ResponseField name="edges" type="array">
    Configurations of the edges connecting nodes within the call flow.
  </ResponseField>
</ResponseField>

<ResponseField name="prompt" type="string">
  The initial or system prompt used in the call flow.
</ResponseField>

<ResponseField name="currentPromptId" type="string">
  ID of the current active prompt version.
</ResponseField>

<ResponseField name="gemini_prompt" type="string">
  Sanitized version of the prompt for Gemini processing.
</ResponseField>

<ResponseField name="startNodeId" type="string">
  ID of the starting node for flow-based configurations.
</ResponseField>

<ResponseField name="isActive" type="boolean">
  Indicates whether the call flow is currently active or inactive.
</ResponseField>

<ResponseField name="agentWebhookUrl" type="string">
  Webhook URL for agent-related events.
</ResponseField>

<ResponseField name="inboundWebhookUrl" type="string">
  Webhook URL for inbound call events.
</ResponseField>

<ResponseField name="dynamicVariableCollections" type="array">
  Array of dynamic variable collections configured for the call flow.
</ResponseField>

<ResponseField name="locations" type="array">
  Array of location objects for visual flow positioning.
</ResponseField>

<ResponseField name="webhooks" type="array">
  Array of configured webhooks with their complete configuration.
</ResponseField>

<ResponseField name="settings" type="object">
  Configuration settings for various aspects of the call flow, including welcome messages, webhooks, knowledge bases, call settings, and security.
  <ResponseField name="security" type="object">
    Security settings with processed values.
    <ResponseField name="hipaaCompliance" type="boolean">
      HIPAA compliance status (processed from securityOptOut).
    </ResponseField>
    <ResponseField name="publicAccess" type="boolean">
      Public access configuration.
    </ResponseField>
  </ResponseField>
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the call flow was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the call flow was last updated.
</ResponseField>


<ResponseExample>
```json
{
  "_id": "676b8e123456789012345678",
  "workspaceId": "6764d172953253138a3a70f4",
  "folderId": null,
  "isGlobal": false,
  "isPreConfigured": false,
  "preConfiguredWorkspaceId": null,
  "name": "Customer Support Flow",
  "direction": "inbound",
  "description": "Handles inbound support calls",
  "agent": "676b8e123456789012345679",
  "promptType": "simple",
  "welcomeMessage": "user_initiated",
  "customWelcomeMessage": "",
  "flowData": {
    "nodes": [
      {
        "id": "node1",
        "type": "start",
        "data": {
          "prompt": "Welcome to our support line. How can I help you?"
        }
      }
    ],
    "edges": []
  },
  "prompt": "Keep the conversation short and friendly.",
  "currentPromptId": "676b8e123456789012345680",
  "promptVersions": [
    {
      "_id": "676b8e123456789012345680",
      "name": "Prompt Version - 1/15/2025, 3:00:00 PM",
      "prompt": "Keep the conversation short and friendly.",
      "metadata": {
        "notes": ""
      },
      "createdAt": "2025-01-15T15:00:00.000Z",
      "updatedAt": "2025-01-15T15:00:00.000Z"
    }
  ],
  "gemini_prompt": "Keep the conversation short and friendly.",
  "startNodeId": null,
  "isActive": true,
  "agentWebhookUrl": "",
  "inboundWebhookUrl": "",
  "dynamicVariableCollections": [],
  "locations": [],
  "webhooks": [],
  "settings": {
    "welcomeMessage": "user_initiated",
    "customWelcomeMessage": "",
    "enableHumanLikeVoiceAndTone": false,
    "welcomeMessageDelay": 0,
    "webhooks": {
      "agent": "",
      "inbound": ""
    },
    "customerLocation": "new york",
    "transfers": [],
    "knowledgeBases": [],
    "utilizePriorCallsContext": false,
    "callSettings": {
      "trilletVoiceGuard": true,
      "reminderMessages": []
    },
    "security": {
      "hipaaCompliance": false,
      "publicAccess": false
    }
  },
  "createdAt": "2025-01-15T15:00:00.000Z",
  "updatedAt": "2025-01-15T15:00:00.000Z"
}
```
</ResponseExample>

---

## Create Message Flow

*Create a new message flow with full settings.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  The name of this message flow (e.g., "New Years Sale").
</ParamField>

<ParamField body="direction" type="string" required>
  Direction of the flow. Possible values: "inbound" "outbound" "bidirectional".
</ParamField>

<ParamField body="description" type="string">
  Short description (e.g., "Handles customer support inquiries via SMS").
</ParamField>

<ParamField body="agent" type="string" required>
  ID of the OmniFlowAgent to associate with this flow.
</ParamField>

<ParamField body="settings" type="object">
  Full configuration object. This can include:
  <Expandable title="settings">
    <ParamField body="responseSettings" type="object">
      <Expandable title="responseSettings">
        <ParamField body="delay" type="number">
          Delay (in seconds) before responding.
        </ParamField>
        <ParamField body="enabled" type="boolean">
          Whether working hours logic is enabled.
        </ParamField>
        <ParamField body="start" type="string">
          Start time for working hours (e.g., "09:00").
        </ParamField>
        <ParamField body="end" type="string">
          End time for working hours (e.g., "17:00").
        </ParamField>
        <ParamField body="timezone" type="string">
          Timezone (e.g., "UTC").
        </ParamField>
        <ParamField body="outOfHoursMessage" type="string">
          Automated reply for out-of-hours messages.
        </ParamField>
      </Expandable>
    </ParamField>
    <ParamField body="security" type="object">
      <Expandable title="security">
        <ParamField body="hipaaCompliance" type="boolean">
          Whether HIPAA compliance is required.
        </ParamField>
      </Expandable>
    </ParamField>
    <ParamField body="emailSettings" type="object">
      <Expandable title="emailSettings">
        <ParamField body="subjectLine" type="string">
          Default subject line for emails sent in this flow.
        </ParamField>
        <ParamField body="signature" type="string">
          Signature appended to email messages.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="initiationMessage" type="string" required>
  The first message that triggers the message flow. This field is essential for
  the generateMessage functionality.
</ParamField>

<ParamField body="prompt" type="string" required>
  A system prompt or instructions for the AI agent.
</ParamField>

<ParamField body="isActive" type="boolean">
  Enable or disable autopilot for this flow (default false).
</ParamField>

<ParamField body="autopilot" type="boolean">
  Enable or disable autopilot for this flow (default false).
</ParamField>

<ParamField body="messageChannel" type="string" required>
  Channel type: "SMS" or "Email".
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the newly created message flow.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the message flow is configured.
</ResponseField>

<ResponseField name="name" type="string">
  The name given to the message flow.
</ResponseField>

<ResponseField name="direction" type="string">
  The direction of the message flow; possible values include "inbound", "outbound", or "bidirectional".
</ResponseField>

<ResponseField name="description" type="string">
  A brief description of what the message flow is designed to handle.
</ResponseField>

<ResponseField name="agent" type="string">
  The identifier of the agent associated with this message flow.
</ResponseField>

<ResponseField name="settings" type="object">
  Configuration settings of the message flow, including response, security, and email settings.
  <ResponseField name="responseSettings" type="object">
    Settings related to response timing and handling within the message flow.
    <ResponseField name="delay" type="number">
      The delay in seconds before a response is issued.
    </ResponseField>
    <ResponseField name="workingHours" type="object">
      Settings defining the working hours during which the message flow is active.
      <ResponseField name="enabled" type="boolean">
        Whether working hours are enabled.
      </ResponseField>
      <ResponseField name="start" type="string">
        The start time of working hours.
      </ResponseField>
      <ResponseField name="end" type="string">
        The end time of working hours.
      </ResponseField>
      <ResponseField name="timezone" type="string">
        The timezone for the working hours.
      </ResponseField>
      <ResponseField name="outOfHoursMessage" type="string">
        The message delivered outside of working hours.
      </ResponseField>
    </ResponseField>
    <ResponseField name="security" type="object">
      Security settings for the message flow.
      <ResponseField name="hipaaCompliance" type="boolean">
        Indicates if HIPAA compliance is enforced.
      </ResponseField>
    </ResponseField>
    <ResponseField name="emailSettings" type="object">
      Settings related to email communication.
      <ResponseField name="subjectLine" type="string">
        The default subject line for emails sent within this flow.
      </ResponseField>
      <ResponseField name="signature" type="string">
        The signature appended to email messages.
      </ResponseField>
    </ResponseField>
  </ResponseField>
</ResponseField>

<ResponseField name="prompt" type="string">
  The system prompt or instructions for the AI agent.
</ResponseField>

<ResponseField name="initiationMessage" type="string">
  The initial message that activates the message flow.
</ResponseField>

<ResponseField name="isActive" type="boolean">
  Indicates whether the message flow is currently active.
</ResponseField>

<ResponseField name="autopilot" type="boolean">
  Indicates whether the autopilot feature of the message flow is enabled.
</ResponseField>

<ResponseField name="messageChannel" type="string">
  The communication channel used by the message flow, such as "SMS" or "Email".
</ResponseField>

<ResponseField name="createdAt" type="string">
  The timestamp when the message flow was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  The timestamp when the message flow was last updated.
</ResponseField>


<ResponseExample>
```json
{
  "_id": "messageFlowId",
  "workspaceId": "workspaceIdExample",
  "name": "Customer Engagement Campaign",
  "direction": "bidirectional",
  "description": "Manages interactions for promotional events via SMS",
  "agent": "agentUniqueId",
  "settings": {
    "responseSettings": {
      "delay": 0,
      "workingHours": {
        "enabled": false,
        "start": "09:00",
        "end": "17:00",
        "timezone": "UTC",
        "outOfHoursMessage": ""
      }
    },
    "security": {
      "hipaaCompliance": false
    },
    "emailSettings": {
      "subjectLine": "Thank You for Joining Our Event",
      "signature": "Best Regards"
    }
  },
  "prompt": "You are a supportive assistant managing event inquiries.",
  "initiationMessage": "Welcome to our service! How can we assist you today?",
  "isActive": true,
  "autopilot": true,
  "messageChannel": "SMS",
  "createdAt": "2025-01-02T10:15:00Z",
  "updatedAt": "2025-01-02T10:15:00Z"
}
```
</ResponseExample>

---

## Delete Message Flow

*Delete an existing message flow.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique ID of the message flow to delete.
</ParamField>

<ResponseExample>
```json 
HTTP/1.1 204 No Content 
```
</ResponseExample>

---

## Get Message Flow

*Retrieve a specific message flow.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique ID of the message flow.
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the message flow.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the message flow is configured.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the message flow.
</ResponseField>

<ResponseField name="direction" type="string">
  Indicates the direction of the message flow, such as "bidirectional".
</ResponseField>

<ResponseField name="description" type="string">
  A brief description of what the message flow is designed to handle.
</ResponseField>

<ResponseField name="agent" type="string">
  The identifier of the agent associated with this message flow.
</ResponseField>

<ResponseField name="settings" type="object">
  The configuration settings for the message flow.
  <ResponseField name="knowledgeBases" type="array">
    An array of knowledge base resources linked to the message flow, if any.
  </ResponseField>
  <ResponseField name="security" type="object">
    Security settings associated with the message flow.
  </ResponseField>
</ResponseField>

<ResponseField name="prompt" type="string">
  The system or initial prompt set for interacting through the message flow.
</ResponseField>

<ResponseField name="isActive" type="boolean">
  Indicates whether the message flow is currently active.
</ResponseField>

<ResponseField name="autopilot" type="boolean">
  Specifies whether autopilot is enabled, allowing the message flow to operate automatically.
</ResponseField>

<ResponseField name="messageChannel" type="string">
  The type of communication channel used by the message flow, such as "SMS".
</ResponseField>

<ResponseField name="createdAt" type="string">
  The timestamp when the message flow was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  The timestamp when the message flow was last updated.
</ResponseField>

<ResponseExample>
```json
{
  "_id": "exampleId1",
  "workspaceId": "exampleWorkspaceId1",
  "name": "My-SMS-Flow",
  "direction": "bidirectional",
  "description": "Example message flow for SMS marketing",
  "agent": "exampleAgentId1",
  "settings": {
    "knowledgeBases": [],
    "security": {}
  },
  "prompt": "You are an AI that handles inbound messages.",
  "isActive": true,
  "autopilot": false,
  "messageChannel": "SMS",
  "createdAt": "2025-01-02T10:15:00Z",
  "updatedAt": "2025-01-02T10:30:00Z"
}
```
</ResponseExample>

---

## List Message Flows

*Retrieve a list of all message flows.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Response Fields

Each object in the response array represents a message flow, containing the following fields:

<ResponseField name="_id" type="string">
  The unique identifier for each message flow.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where each message flow is configured.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the message flow.
</ResponseField>

<ResponseField name="direction" type="string">
  Indicates the direction of the message flow, such as "bidirectional" or "outbound".
</ResponseField>

<ResponseField name="description" type="string">
  A brief description of what the message flow is designed to handle.
</ResponseField>

<ResponseField name="agent" type="string">
  The identifier of the agent associated with this message flow.
</ResponseField>

<ResponseField name="settings" type="object">
  The configuration settings for the message flow. This field may contain various subfields depending on the specific configurations set for each flow.
</ResponseField>

<ResponseField name="prompt" type="string">
  The system or initial prompt set for interacting through the message flow.
</ResponseField>

<ResponseField name="isActive" type="boolean">
  Indicates whether the message flow is currently active.
</ResponseField>

<ResponseField name="autopilot" type="boolean">
  Specifies whether autopilot is enabled, allowing the message flow to operate automatically.
</ResponseField>

<ResponseField name="messageChannel" type="string">
  The type of communication channel used by the message flow, such as "SMS" or "Email".
</ResponseField>

<ResponseField name="createdAt" type="string">
  The timestamp when the message flow was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  The timestamp when the message flow was last updated.
</ResponseField>

<ResponseExample>
```json
[
  {
    "_id": "exampleId1",
    "workspaceId": "exampleWorkspaceId1",
    "name": "SMS Flow #1",
    "direction": "bidirectional",
    "description": "Example #1",
    "agent": "exampleAgentId1",
    "settings": {},
    "prompt": "Short prompt for AI",
    "isActive": true,
    "autopilot": false,
    "messageChannel": "SMS",
    "createdAt": "2025-01-02T10:15:00Z",
    "updatedAt": "2025-01-02T10:30:00Z"
  },
  {
    "_id": "exampleId2",
    "workspaceId": "exampleWorkspaceId2",
    "name": "Email Nurture Flow",
    "direction": "outbound",
    "description": "Send follow-up emails to leads",
    "agent": "exampleAgentId2",
    "settings": {},
    "prompt": "You are an email follow-up AI.",
    "isActive": false,
    "autopilot": false,
    "messageChannel": "Email",
    "createdAt": "2025-01-03T11:00:00Z",
    "updatedAt": "2025-01-03T11:15:00Z"
  }
]

```
</ResponseExample>

---

## Toggle Autopilot

*Toggle the autopilot mode of an existing message flow.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique ID of the message flow where autopilot will be toggled.
</ParamField>

<ParamField type="string" body="" default="s" optional hidden>
  An optional, empty object as the default body.
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the message flow where autopilot was toggled.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace containing the message flow.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the message flow.
</ResponseField>

<ResponseField name="description" type="string">
  A description of what the message flow is designed to handle.
</ResponseField>

<ResponseField name="agent" type="string">
  The identifier of the agent associated with this message flow.
</ResponseField>

<ResponseField name="prompt" type="string">
  The system or initial prompt set for the AI agent in the message flow.
</ResponseField>

<ResponseField name="initiationMessage" type="string">
  The initial message that triggers the message flow. This is crucial for the generateMessage functionality.
</ResponseField>

<ResponseField name="isActive" type="boolean">
  Indicates whether the message flow is currently active.
</ResponseField>

<ResponseField name="autopilot" type="boolean">
  Shows the current state of autopilot for this message flow after toggling. If true, autopilot is now enabled; if false, it is now disabled.
</ResponseField>

<ResponseField name="messageChannel" type="string">
  The type of communication channel used by the message flow, such as "SMS".
</ResponseField>

<ResponseField name="createdAt" type="string">
  The timestamp when the message flow was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  The timestamp the last time the message flow was updated.
</ResponseField>


<ResponseExample>
```json
{
  "_id": "1234567890abcdef12345678",
  "workspaceId": "abcdef1234567890abcdef12",
  "name": "SampleFlow",
  "description": "Sample description for the flow.",
  "agent": "0987654321fedcba09876543",
  "prompt": "You are a helpful assistant.",
  "initiationMessage": "Hello!",
  "isActive": true,
  "autopilot": true,
  "messageChannel": "SMS",
  "createdAt": "2025-01-01T12:00:00.000Z",
  "updatedAt": "2025-01-15T08:30:00.000Z"
}

```
</ResponseExample>

---

## Update Message Flow

*Update an existing message flow with partial or full settings.*

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the message flow to update.
</ParamField>

### Request Body

<ParamField body="description" type="string">
  Update the description for this message flow.
</ParamField>

<ParamField body="toggleAutopilot" type="boolean">
  If present and set to true, this toggles the autopilot setting.
</ParamField>

<ParamField body="settings" type="object">
  Configuration settings for the message flow.

  <Expandable title="settings">
    <ParamField body="responseSettings" type="object">
      <Expandable title="responseSettings">
        <ParamField body="delay" type="number">
          Delay (in seconds) before responding.
        </ParamField>
        <ParamField body="workingHours" type="object">
          <Expandable title="workingHours">
            <ParamField body="enabled" type="boolean">
              Whether working hours logic is enabled.
            </ParamField>
            <ParamField body="start" type="string">
              Start time for working hours, e.g., "09:00".
            </ParamField>
            <ParamField body="end" type="string">
              End time for working hours, e.g., "17:00".
            </ParamField>
            <ParamField body="timezone" type="string">
              Timezone for working hours, e.g., "UTC".
            </ParamField>
            <ParamField body="outOfHoursMessage" type="string">
              Automated reply for out-of-hours messages.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
    <ParamField body="security" type="object">
      <Expandable title="security">
        <ParamField body="hipaaCompliance" type="boolean">
          Whether HIPAA compliance is required.
        </ParamField>
      </Expandable>
    </ParamField>
    <ParamField body="emailSettings" type="object">
      <Expandable title="emailSettings">
        <ParamField body="subjectLine" type="string">
          Default subject line for emails sent in this flow, e.g., "Follow Up on Your Inquiry".
        </ParamField>
        <ParamField body="signature" type="string">
          Signature appended to email messages, e.g., "Regards".
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the message flow that was updated.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the message flow is configured.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the message flow. While not specified as updated in the request body, it remains a critical part of the response for context.
</ResponseField>

<ResponseField name="direction" type="string">
  Indicates the direction of the message flow, such as "bidirectional".
</ResponseField>

<ResponseField name="description" type="string">
  The updated description of what the message flow is designed to handle.
</ResponseField>

<ResponseField name="agent" type="string">
  The identifier of the agent associated with this message flow.
</ResponseField>

<ResponseField name="settings" type="object">
  The configuration settings for the message flow, detailing updated and existing settings.
  <ResponseField name="responseSettings" type="object">
    Settings related to the timing and conditions under which responses are issued within the message flow.
    <ResponseField name="delay" type="number">
      The delay in seconds before a response is issued.
    </ResponseField>
    <ResponseField name="workingHours" type="object">
      Configuration for working hours during which the message flow is active.
      <ResponseField name="enabled" type="boolean">
        Whether working hours are enabled.
      </ResponseField>
      <ResponseField name="start" type="string">
        Start time of the working hours.
      </ResponseField>
      <ResponseField name="end" type="string">
        End time of the working hours.
      </ResponseField>
      <ResponseField name="timezone" type="string">
        Timezone applicable to the working hours.
      </ResponseField>
      <ResponseField name="outOfHoursMessage" type="string">
        Message to be delivered outside of working hours.
      </ResponseField>
    </ResponseField>
  </ResponseField>
  <ResponseField name="security" type="object">
    Security settings for the message flow, including HIPAA compliance status.
    <ResponseField name="hipaaCompliance" type="boolean">
      Indicates if HIPAA compliance is enforced.
    </ResponseField>
  </ResponseField>
  <ResponseField name="emailSettings" type="object">
    Email settings for managing email-based message flows.
    <ResponseField name="subjectLine" type="string">
      The subject line used for emails sent in this flow.
    </ResponseField>
    <ResponseField name="signature" type="string">
      The email signature appended to messages.
    </ResponseField>
  </ResponseField>
</ResponseField>

<ResponseField name="prompt" type="string">
  The system or initial prompt set for the AI agent in the message flow.
</ResponseField>

<ResponseField name="isActive" type="boolean">
  Indicates whether the message flow is currently active.
</ResponseField>

<ResponseField name="autopilot" type="boolean">
  Specifies whether autopilot is enabled or disabled after the update.
</ResponseField>

<ResponseField name="messageChannel" type="string">
  The type of communication channel used by the message flow, such as "SMS".
</ResponseField>

<ResponseField name="createdAt" type="string">
  The timestamp when the message flow was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  The timestamp when the message flow was last updated.
</ResponseField>


<ResponseExample>
```json
{
  "_id": "exampleId1",
  "workspaceId": "exampleWorkspaceId1",
  "name": "New Years Sale",
  "direction": "bidirectional",
  "description": "Handles customer support inquiries via SMS",
  "agent": "exampleAgentId1",
  "settings": {
    "responseSettings": {
      "delay": 0,
      "workingHours": {
        "enabled": false,
        "start": "09:00",
        "end": "17:00",
        "timezone": "UTC",
        "outOfHoursMessage": ""
      }
    },
    "security": {
      "hipaaCompliance": false
    },
    "emailSettings": {
      "subjectLine": "Follow Up on Your Inquiry",
      "signature": "Regards"
    }
  },
  "prompt": "You are a helpful AI that responds to user inquiries.",
  "isActive": true,
  "autopilot": true,
  "messageChannel": "SMS",
  "createdAt": "2025-01-02T10:15:00Z",
  "updatedAt": "2025-01-02T10:15:00Z"
}

```
</ResponseExample>

---

## Disconnect Google Calendar

*Disconnect Google Calendar integration from a call flow.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Query Parameters

<ParamField query="pathwayId" type="string" required>
The call flow pathway ID to disconnect Google Calendar from.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the disconnection was successful.
</ResponseField>

<ResponseExample>
```json
{
  "success": true
}
```
</ResponseExample>

---

## Install Google Calendar

*Get the Google Calendar OAuth authorization URL to connect your Google Calendar.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Query Parameters

<ParamField query="pathwayId" type="string" required>
The call flow pathway ID to connect Google Calendar to.
</ParamField>

## Response Fields

<ResponseField name="url" type="string">
The Google OAuth authorization URL. Redirect the user to this URL to authorize the connection.
</ResponseField>

<ResponseExample>
```json
{
  "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&scope=...&state=..."
}
```
</ResponseExample>

---

## List Google Calendars

*List all available Google Calendars for the connected account.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Query Parameters

<ParamField query="pathwayId" type="string" required>
The call flow pathway ID with the Google Calendar connection.
</ParamField>

## Response Fields

<ResponseField name="calendars" type="array">
Array of available calendars.

<ResponseField name="id" type="string">
Calendar ID.
</ResponseField>

<ResponseField name="summary" type="string">
Calendar name/title.
</ResponseField>

<ResponseField name="primary" type="boolean">
Whether this is the primary calendar.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
{
  "calendars": [
    {
      "id": "primary",
      "summary": "John Doe",
      "primary": true
    },
    {
      "id": "appointments@company.com",
      "summary": "Appointments",
      "primary": false
    }
  ]
}
```
</ResponseExample>

---

## Disconnect GoHighLevel

*Disconnect GoHighLevel CRM integration from a call flow.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Query Parameters

<ParamField query="pathwayId" type="string" required>
The call flow pathway ID to disconnect GoHighLevel from.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the disconnection was successful.
</ResponseField>

<ResponseExample>
```json
{
  "success": true
}
```
</ResponseExample>

---

## Install GoHighLevel

*Get the GoHighLevel OAuth authorization URL to connect your GHL CRM.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Query Parameters

<ParamField query="pathwayId" type="string" required>
The call flow pathway ID to connect GoHighLevel to.
</ParamField>

## Response Fields

<ResponseField name="url" type="string">
The GoHighLevel OAuth authorization URL. Redirect the user to this URL to authorize the connection.
</ResponseField>

<ResponseExample>
```json
{
  "url": "https://marketplace.gohighlevel.com/oauth/chooselocation?response_type=code&client_id=...&redirect_uri=...&state=..."
}
```
</ResponseExample>

---

## Configure Meta Lead Ads

*Configure Meta Lead Ads integration for a specific call flow. When a new lead is received, it automatically triggers a call.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="flowId" type="string" required>
The call flow ID to configure Meta Lead Ads for.
</ParamField>

## Request Body

<ParamField body="clientId" type="string" required>
Meta App client ID.
</ParamField>

<ParamField body="clientSecret" type="string" required>
Meta App client secret.
</ParamField>

<ParamField body="userAccessToken" type="string" required>
Meta user access token from the OAuth flow.
</ParamField>

<ParamField body="callDelaySeconds" type="number" default="0">
Delay in seconds before calling a new lead.
</ParamField>

<ParamField body="selectedPages" type="array" required>
Array of Facebook pages and lead forms to monitor.

<Expandable title="properties">

<ParamField body="pageId" type="string" required>
Facebook page ID.
</ParamField>

<ParamField body="forms" type="array" required>
Array of lead form IDs to monitor on this page.
</ParamField>

</Expandable>
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the configuration was successful.
</ResponseField>

<ResponseField name="webhookRegistered" type="boolean">
Whether the webhook was successfully registered with Meta.
</ResponseField>

<ResponseExample>
```json
{
  "success": true,
  "webhookRegistered": true
}
```
</ResponseExample>

---

## Install Meta Lead Ads

*Get the Meta OAuth authorization URL to connect Meta Lead Ads for automatic lead calling.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Response Fields

<ResponseField name="url" type="string">
The Meta OAuth authorization URL. Redirect the user to this URL to authorize the Meta Lead Ads connection.
</ResponseField>

<ResponseExample>
```json
{
  "url": "https://www.facebook.com/v18.0/dialog/oauth?client_id=...&redirect_uri=...&scope=...&state=..."
}
```
</ResponseExample>

---

## Get Meta Lead Ads Status

*Check the connection and configuration status of Meta Lead Ads for a specific call flow.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="flowId" type="string" required>
The call flow ID to check the Meta Lead Ads status for.
</ParamField>

## Response Fields

<ResponseField name="connected" type="boolean">
Whether Meta Lead Ads is connected and configured for this flow.
</ResponseField>

<ResponseField name="pages" type="array">
Configured Facebook pages and their forms.
</ResponseField>

<ResponseField name="callDelaySeconds" type="number">
Current call delay setting in seconds.
</ResponseField>

<ResponseExample>
```json
{
  "connected": true,
  "pages": [
    {
      "pageId": "123456789",
      "pageName": "My Business Page",
      "forms": ["form_001", "form_002"]
    }
  ],
  "callDelaySeconds": 30
}
```
</ResponseExample>

---

## Authorize Meta WhatsApp

*Get the Meta OAuth authorization URL to connect your WhatsApp Business Account.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Response Fields

<ResponseField name="url" type="string">
The Meta OAuth authorization URL. Redirect the user to this URL to authorize the WhatsApp Business connection.
</ResponseField>

<ResponseExample>
```json
{
  "url": "https://www.facebook.com/v18.0/dialog/oauth?client_id=...&redirect_uri=...&scope=...&state=..."
}
```
</ResponseExample>

---

## Disconnect Meta WhatsApp

*Disconnect the Meta WhatsApp Business integration from your workspace.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
Whether the disconnection was successful.
</ResponseField>

<ResponseExample>
```json
{
  "success": true
}
```
</ResponseExample>

---

## Get WhatsApp Connection Status

*Check the current connection status of your Meta WhatsApp Business integration.*

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Response Fields

<ResponseField name="connected" type="boolean">
Whether the WhatsApp Business Account is connected.
</ResponseField>

<ResponseField name="wabaId" type="string">
The WhatsApp Business Account ID (if connected).
</ResponseField>

<ResponseField name="wabaName" type="string">
The WhatsApp Business Account name (if connected).
</ResponseField>

<ResponseField name="businessName" type="string">
The Meta Business name (if connected).
</ResponseField>

<ResponseExample>
```json
{
  "connected": true,
  "wabaId": "123456789",
  "wabaName": "My Business WhatsApp",
  "businessName": "My Company Inc."
}
```
</ResponseExample>

---