# AI Prompt Editor
Source: https://docs.autocalls.ai/ai-assistants/ai-prompt-editor

Edit and improve your assistant's prompts using AI-powered suggestions through a conversational interface

The AI Prompt Editor is an intelligent tool that allows you to edit and improve your AI assistant's prompts using natural language. Instead of manually editing text, you can chat with an AI assistant that understands your requests and suggests intelligent modifications.

## Overview

The AI Prompt Editor provides:

* **Conversational editing** - Describe changes in plain language
* **Smart suggestions** - AI understands context and makes relevant changes
* **Review before apply** - Accept or reject each change individually
* **Variable management** - Easily manage pre-call and post-call data
* **Template library** - Start with proven prompt templates

<Frame>
  <img alt="AI Prompt Editor Interface" />
</Frame>

## Getting Started

<Steps>
  <Step title="Open your assistant">
    Navigate to **Assistants** in the sidebar and click on the assistant you want to edit.
  </Step>

  <Step title="Find the AI Prompt Editor">
    In the edit form, scroll to the **System Prompt** section and find the **AI Prompt Editor** tab.
  </Step>

  <Step title="Launch the editor">
    Click the **Launch AI Prompt Editor** button. A modal window will open with the editor interface.
  </Step>
</Steps>

<Note>
  You must save your assistant at least once before you can use the AI Prompt Editor.
</Note>

## Interface Overview

The AI Prompt Editor has three main areas:

### Chat Panel (Left Side)

This is where you interact with the AI:

* Type your requests in the input box at the bottom
* View conversation history above
* Use quick suggestion chips for common actions:
  * **Make it more concise** - Shorten the prompt
  * **Add more detail** - Expand with specifics
  * **Improve clarity** - Make instructions clearer
  * **Add instructions** - Add new behavioral guidelines

### Editor Panel (Right Side)

This shows your current prompt with two tabs:

* **System Prompt** - The main instructions for your assistant
* **Initial Message** - The greeting message when calls start

Toggle between **Edit** mode (textarea) and **Preview** mode (formatted view with diff highlights).

### Side Tabs

* **Variables** - Manage pre-call data variables
* **Post-Call** - Define data to collect after calls

## Using the Chat

### Making Requests

Simply describe what you want to change:

<AccordionGroup>
  <Accordion title="Example: Make the tone friendlier">
    **You:** "Make the tone more friendly and casual"

    **AI:** The AI will suggest changes to make greetings warmer, use more conversational language, and soften formal phrases.
  </Accordion>

  <Accordion title="Example: Add information">
    **You:** "Add information about our return policy - 30 days no questions asked"

    **AI:** The AI will find the appropriate place in your prompt and add the return policy details.
  </Accordion>

  <Accordion title="Example: Handle a scenario">
    **You:** "Add instructions for handling angry customers"

    **AI:** The AI will add behavioral guidelines for de-escalation and when to transfer to a human.
  </Accordion>
</AccordionGroup>

### Tips for Better Results

* **Be specific** - "Add a 10% discount mention" is better than "add discount info"
* **Provide context** - "When asked about pricing, mention..." gives AI better understanding
* **One change at a time** - Break complex changes into multiple requests

## Reviewing Changes

When the AI suggests changes, they appear in the diff view:

* **Green highlighting** - New text being added
* **Red highlighting** - Text being removed
* **Blue highlighting** - Text being modified

### Accept or Reject Changes

Each change has two buttons:

* **✓ Accept** - Apply this specific change
* **✗ Reject** - Discard this change

You can also use bulk actions:

* **Accept All** - Apply all pending changes
* **Reject All** - Discard all pending changes

<Warning>
  Always review changes before accepting. The AI makes intelligent suggestions, but you know your business best.
</Warning>

<Frame>
  <img alt="Reviewing Changes with Diff View" />
</Frame>

## Variables

Variables allow you to personalize calls with dynamic data.

### Adding Variables

1. Click the **Variables** tab
2. Click **Add Variable**
3. Enter a name (e.g., `customer_name`, `appointment_time`)
4. Set a default value

### Using Variables in Prompts

Type variables directly in your prompt using curly braces: `{variable_name}`

**Example prompt:**

```
Hello {customer_name}, I'm calling from {company_name} about your appointment on {appointment_date}.
```

## Post-Call Schema

Define structured data you want to collect during or after calls.

### Adding Post-Call Fields

1. Click the **Post-Call** tab
2. Click **Add Field**
3. Configure:
   * **Name** - Field identifier (e.g., `meeting_scheduled`)
   * **Type** - `string`, `number`, or `boolean`
   * **Description** - What this field captures

### Example Fields

| Name                | Type    | Description                          |
| ------------------- | ------- | ------------------------------------ |
| `meeting_scheduled` | boolean | Whether a meeting was booked         |
| `interest_level`    | string  | Customer's interest: hot, warm, cold |
| `callback_time`     | string  | Preferred callback date/time         |
| `objection_reason`  | string  | Main objection if not interested     |

<Tip>
  The AI can suggest post-call fields based on your prompt. Just ask: "What data should I collect from these calls?"
</Tip>

<Frame>
  <img alt="Post-Call Fields Configuration" />
</Frame>

## Templates

When you first open the AI Prompt Editor, you can choose to start with a template:

* **Continue with existing** - Keep your current prompt
* **Start from scratch** - Begin with a blank prompt
* **Start with template** - Choose from pre-built templates

Templates are organized by use case:

* Sales calls
* Customer support
* Appointment scheduling
* Surveys and feedback
* Lead qualification

<Frame>
  <img alt="Template Selection Screen" />
</Frame>

## Saving Your Work

Click the **Save** button in the top-right to save all changes to your assistant.

<Note>
  The editor auto-detects unsaved changes. If you try to close with unsaved work, you'll be prompted to save or discard.
</Note>

## Best Practices

<CardGroup>
  <Card title="Start with Templates" icon="layer-group">
    Templates provide proven starting points. Customize rather than starting from zero.
  </Card>

  <Card title="Iterate Gradually" icon="repeat">
    Make small changes, test, and refine. Don't overhaul everything at once.
  </Card>

  <Card title="Review Every Change" icon="magnifying-glass">
    The AI is helpful but not perfect. Always review suggestions before accepting.
  </Card>

  <Card title="Test After Editing" icon="phone">
    Make test calls after changes to verify the assistant behaves as expected.
  </Card>
</CardGroup>

## Related Resources

* [System Prompts Guide](/ai-assistants/system-prompt) - Deep dive into prompt writing
* [Flow Builder](/ai-assistants/flow-builder) - Visual alternative for conversation design
* [Testing Your Assistant](/ai-assistants/testing) - How to test your changes


# Assistant best practices
Source: https://docs.autocalls.ai/ai-assistants/assistant-configuration

Quick guide to fine-tune mode, transcriber, model, and other settings for the best call experience.

> **Last updated:** September 5, 2026

Getting great results often comes down to **picking the right engine settings**. Use this checklist when configuring an assistant:

## 1. Pick a Mode

| Mode                              | Why choose it?                                 | Notes                                                                                                  |
| --------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Dualplex (Beta)**               | Fast turn-taking + premium/cloned voices       | Recommended default. Pair with **GPT Realtime**. Gemini is Speech-to-Speech only.                      |
| **Speech-to-Speech (Multimodal)** | Fastest turn-taking & most natural flow        | Recommended model: **GPT‑5 Realtime**.                                                                 |
| **Pipeline**                      | Maximum control over voice & long-form replies | Recommended model: **GPT‑5 Mini**. If you select Pipeline, continue to the **Transcriber** step below. |

Want to know more about the differences between the modes? Read the <a href="/ai-assistants/assistant-modes">Assistant modes</a> guide.

<Note>
  Experiment with all three modes: record the same scenario in each and compare response time and caller satisfaction.<br />
</Note>

## 2. Choose a Transcriber (Pipeline only)

| Transcriber  | Accuracy | Latency         | Best for                                                                         |
| ------------ | -------- | --------------- | -------------------------------------------------------------------------------- |
| **Azure**    | ⭐⭐⭐⭐     | ⏱️⏱️⏱️ (slower) | When you need the highest transcription fidelity.                                |
| **Gladia**   | ⭐⭐⭐      | ⏱️ (faster)     | Good all-rounder for most languages.                                             |
| **Deepgram** | ⭐⭐⭐      | ⏱️ (faster)     | Another solid choice—test which performs better for your language & audio setup. |

> **Tip:** Different languages, accents, or background noise can impact each engine differently. Run a quick A/B test and keep the best performer.

## 3. Select an LLM Model

| Model                      | Strengths                                     | Trade-offs                                                               |
| -------------------------- | --------------------------------------------- | ------------------------------------------------------------------------ |
| **GPT-5 Mini**             | Balanced reasoning with low latency           | May be slower than realtime models for rapid turn-taking.                |
| **GPT-5 Realtime**         | Designed for ultra-low-latency voice turns    | Best for **Speech-to-Speech** and **Dualplex**.                          |
| **GPT-4o**                 | Strong reasoning and multimodal understanding | Higher latency.                                                          |
| **Gemini Flash 2.0 / 2.5** | Ultra-fast native audio for voice turns       | **Speech-to-Speech** only. Dualplex needs GPT Realtime so TTS can speak. |

If speed is critical, use **GPT Realtime** for Dualplex or Speech-to-Speech, or **Gemini** in Speech-to-Speech. For richer reasoning, use **GPT-4o** or **GPT-5 Mini** and offset latency by using filler audios.

## 4. Noise Cancellation

If callers are on speaker phone or in a quiet environment, keep **noise cancellation ON**. If your call volume is low or some words are "clipped," **turn it OFF** so the transcriber gets the full waveform.

<Note>
  If your assistant is not hearing you well, you can try to turn off noise cancellation.
</Note>

## 5. Conversation Timers

| Parameter                | Recommended | Why                                                                |
| ------------------------ | ----------- | ------------------------------------------------------------------ |
| **Re-engagement**        | `≈ 30 s`    | Gives callers enough time to think. Lower values can feel pushy.   |
| **Max silence duration** | `≈ 60 s`    | Prevents premature hang-ups while still ending truly silent calls. |

Test different values in real calls—too low can interrupt, too high leaves awkward gaps.

## 6. Initial Message

| Mode                 | How it's used                                              | Best practice                                                                                                   |
| -------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Pipeline**         | Read **exactly** as written (converted by TTS).            | Write the greeting verbatim: "Hello, this is Alex from …".                                                      |
| **Dualplex**         | Read **exactly** as written (rendered via ElevenLabs TTS). | Write the greeting verbatim, then select your cloned voice.                                                     |
| **Speech-to-Speech** | Interpreted as a **prompt** by the model.                  | Include instructions like "Greet the customer and say …" *or* prepend `say exactly: ` to ensure literal output. |

## 7. Ambient sound

Enabled by default, ambient sound is a feature that adds background noise to the assistant's voice.

<Note>
  If the assistant is not hearing you well, you can try to turn off ambient sound or turn the volume lower.
</Note>

## 8. Endpointing sliders

**Control when your assistant starts talking** with the endpointing sensitivity slider at the bottom of assistant settings.

| Setting                | Effect                                                    | Use when                                   |
| ---------------------- | --------------------------------------------------------- | ------------------------------------------ |
| **Lower sensitivity**  | Assistant responds **faster** after caller stops speaking | You want snappy, quick-turn conversations  |
| **Higher sensitivity** | Assistant waits **longer** before responding              | Callers give longer, more detailed replies |

<Tip>
  **Pro tip:** If your assistant cuts off callers mid-sentence, **increase** the sensitivity. If responses feel sluggish, **decrease** it.
</Tip>

## 9. Debug using call transcript

If you are having issues with your assistant, you can use the call transcript to debug the issue.

1. Go to the Call history page.
2. Click on the last call you tested
3. The call transcript will be shown including function calls and its parameters.

## 10. Still have questions?

If you have any questions, please contact our support team via the chat widget inside the app.

<Note>
  Test different settings with real calls—the right balance depends on your conversation flow and caller behavior patterns.
</Note>

***

Need a complete list of every toggle and slider? See the full
<a href="/ai-assistants/settings/general">Assistant settings reference</a>.


# Assistant Modes
Source: https://docs.autocalls.ai/ai-assistants/assistant-modes

Understand the three voice generation modes available for your AI assistants and when to use each one.

AI assistants on Autocalls.ai can speak in **three distinct modes**. Each mode determines how a caller's speech is understood and how the assistant's reply is generated:

<Callout>
  Choosing the right mode can improve response time, naturalness, and overall call experience.
</Callout>

## 1. Pipeline

|                  |                                                            |
| ---------------- | ---------------------------------------------------------- |
| **Label in UI**  | `Pipeline`                                                 |
| **How it works** | Speech-to-Text → LLM → Text-to-Speech                      |
| **Latency**      | \~800 – 1500 ms (depends on language & model)              |
| **Best for**     | Complex reasoning, dynamic prompts, multi-sentence replies |

Pipeline mode first transcribes the caller's words into text, runs that text through the language model, then converts the response back to audio. It's a tried-and-true approach that offers maximum flexibility:

* Supports **all voices** in the library (including custom-cloned voices).
* Handles **long-form answers** or paragraph-style responses well.
* Allows the LLM to **inject variables** and reference earlier context cleanly.

### When to choose Pipeline

1. You need rich, multi-sentence answers (e.g.
   support queries, detailed explanations).
2. The assistant must reason over **structured data** or complex prompts.
3. You prefer absolute control of the spoken voice (clone or brand voice).

## 2. Speech-to-Speech (Multimodal)

|                  |                                                               |
| ---------------- | ------------------------------------------------------------- |
| **Label in UI**  | `Speech-to-speech`                                            |
| **How it works** | Direct **speech-to-speech** generation (no intermediate text) |
| **Latency**      | \~300 – 600 ms (ultra low)                                    |
| **Best for**     | Natural back-and-forth, short & reactive replies              |

Speech-to-speech mode skips separate transcription and TTS. Instead, it uses a **multimodal model** that listens and speaks directly, producing more conversational flow:

* **Fast turn-taking** – callers experience near-instant responses.
* Generates **more expressive prosody** natively (intonation, fillers).
* Currently supports a **limited voice set**, but more are added regularly.

### When to choose Speech-to-Speech

1. The conversation needs to feel **snappy** (sales, booking confirmations).
2. Your replies are generally **short sentences** or quick acknowledgements.
3. You're okay with the system-provided voice options for faster interaction.

<Note>
  Speech-to-speech is evolving rapidly. If you need a custom cloned voice with low latency, try **Dualplex**.
</Note>

## 3. Dualplex (Beta)

|                  |                                                                    |
| ---------------- | ------------------------------------------------------------------ |
| **Label in UI**  | `Dualplex`                                                         |
| **How it works** | Multimodal STT + LLM (speech-to-speech) with ElevenLabs TTS output |
| **Latency**      | Low (varies by voice and model)                                    |
| **Best for**     | Fast, natural replies with high-quality/brand voices (cloned)      |

Dualplex blends the responsiveness of speech-to-speech with the premium voices and cloning from ElevenLabs used in Pipeline. The assistant uses the multimodal model to understand the caller and plan the reply, then renders the final speech through ElevenLabs for consistent, high‑fidelity output.

* **Near-instant turn-taking** similar to speech-to-speech.
* Access to **ElevenLabs** voice library, including **custom-cloned voices**.
* Great for **short to medium** replies with expressive prosody.
* **Recommended default** for most use-cases today; currently in **Beta**.
* Use a **GPT Realtime** model. Gemini native-audio models only work in Speech-to-speech.

### When to choose Dualplex

1. You want fast back-and-forth but need a branded or cloned voice.
2. You want more expressive delivery without giving up precise voice choice.
3. You're comfortable using a new feature that is still in Beta.

## Switching modes

You can pick the mode for each assistant in **Assistant → Settings → Voice Engine**. Test all three modes to see which delivers the best balance of speed and quality for your use-case. `Dualplex` is currently labeled **Beta**.

***

**Pro Tip:** Record two calls – one in each mode – and compare the caller's perceived latency and engagement level to decide which fits your flow.


# Cal.com Appointment Scheduling
Source: https://docs.autocalls.ai/ai-assistants/cal-com-scheduling

Enable your AI assistant to schedule appointments using Cal.com

Enable your AI assistant to schedule meetings using Cal.com integration. The system automatically configures booking fields for you.

## Setup

### 1. Get API Key

1. Log in to [Cal.com](https://cal.com/)
2. Go to **Settings** → **Developer** → **API Keys**
3. Create a new API key and copy it

<img />

### 2. Select Your Region

Cal.com offers different API regions. Choose the one that matches your Cal.com account:

| Region           | API Endpoint                      |
| ---------------- | --------------------------------- |
| **US** (default) | `api.cal.com`                     |
| **EU**           | `api.cal.eu`                      |
| **Custom**       | Your self-hosted Cal.com endpoint |

Select your region in the Cal.com configuration panel before connecting. If you're unsure, the US endpoint is the default.

### 3. Connect Cal.com

1. In your assistant settings → **Tools** tab → **Appointment Scheduling**
2. Select **Cal.com** from calendar type
3. Choose your API region
4. Paste your API key
5. Select an event from the dropdown

<img />

### 4. Sync Event

Click the **"Sync Event"** button to automatically configure booking fields.

<img />

<Check>
  The sync automatically reads your event type's custom fields and configures them for the AI assistant. Name, email, and phone are set as required. All other custom booking fields are imported automatically.
</Check>

## Event Types

### Personal Events

Select from your personal event types (e.g., 15-minute intro call, 30-minute consultation).

### Team Events

You can also book into **team event types**. When your API key has access to team calendars, team events appear in the event dropdown grouped separately from personal events.

<Tip>
  Team events are useful when you want the AI to book meetings that get distributed across your team members based on their availability.
</Tip>

## Dynamic Booking Fields

When you sync an event, the system automatically reads all custom booking fields configured on that event type in Cal.com. This means:

* **No manual field configuration** — fields are fetched directly from your Cal.com event type
* **Custom fields supported** — any custom fields you add to your Cal.com event type are automatically available
* **Auto-refresh on sync** — click "Sync Event" again if you change your Cal.com event's booking fields

## Multiple Calendars

Click **"+"** next to Appointment Scheduling to add more calendars (e.g., 15min, 30min meetings).

## Email Setup

For calendar invites to work:

1. Define `email` in assistant [input variables](/ai-assistants/settings/prompt-and-tools#call-variables)
2. Pass customer email when creating leads

The phone number is automatically included after sync.

## Backward Compatibility

If you already have a Cal.com integration configured, your existing settings continue to work without changes. The region defaults to US, and existing field configurations are preserved. You can optionally re-sync to take advantage of dynamic booking fields.

## Troubleshooting

**Invalid API Key:** Verify it's active in Cal.com settings and includes `cal_live_` prefix

**Sync Failed:** Click **"Troubleshoot"** button to reset fields

**No Invites Sent:** Ensure `email` variable is defined and passed with leads

**Field Errors:** Use "Troubleshoot" to reset. Only name, email, phone should be required.

**Wrong Region:** If you get authentication errors, check that you selected the correct region (EU accounts must use the EU endpoint).

<Note>
  For detailed troubleshooting, see [Cal.com Issues](/troubleshooting/cal-com).
</Note>

## Testing

1. Make a test call and request a meeting
2. Verify booking appears in Cal.com
3. Check calendar invitation email was received


# Calendly Appointment Scheduling
Source: https://docs.autocalls.ai/ai-assistants/calendly-scheduling

Enable your AI assistant to schedule appointments using Calendly

Enable your AI assistant to schedule meetings using Calendly integration. The AI will check availability and book appointments directly during calls.

## Prerequisites

* An active Calendly account
* At least one active event type configured in Calendly

## Setup

### 1. Connect Calendly

1. In your assistant settings, go to **Tools** tab → **Appointment Scheduling**
2. Select **Calendly** as the calendar type
3. Click **Connect to Calendly**
4. Authorize the application on the Calendly OAuth page
5. You'll be redirected back to your assistant settings

<Note>
  If you have issues connecting, try using an **incognito/private browser window** to resolve authentication conflicts.
</Note>

### 2. Select Event Type

1. Once connected, click **"Load Events"** to fetch your Calendly event types
2. Select the event type you want the AI to use for bookings
3. Save your assistant

### 3. Configure Location in Calendly

Your Calendly event type's location setting must be compatible with the voice agent.

1. Go to [calendly.com](https://calendly.com) → **Event Types**
2. Edit the event type linked to your assistant
3. In the **Location** section, set it to one of:
   * **"Custom"** — recommended, works in all cases
   * **"Phone Call" → "Inbound call"** — also works for voice AI

<Warning>
  If your event type uses only video conferencing (Google Meet, Zoom, Teams), bookings will fail. The voice agent cannot generate meeting links. Either switch to "Custom" or add it as an additional location option.
</Warning>

## Multiple Calendars

Click **"+"** next to Appointment Scheduling to add more calendar tools (e.g., different event types for different purposes). Use the "When to schedule" description to help the AI pick the right calendar.

## Organization Accounts

If your Calendly account is part of an organization:

* **Admin/Owner accounts** can see all event types across team members, including Round Robin and Collective events
* **Regular members** can only see their own event types

## Testing

1. Make a test call and request to schedule a meeting
2. Verify the booking appears in your Calendly dashboard
3. Check that the calendar invitation was sent

<Note>
  For troubleshooting, see [Calendly Issues](/troubleshooting/calendly).
</Note>


# Custom Mid-Call Tools
Source: https://docs.autocalls.ai/ai-assistants/custom-tools

Learn how to create and configure custom API integrations that your AI assistant can use during calls

<Note>
  Custom Mid-Call Tools let your AI assistant interact with external systems
  during calls. Whether checking inventory, verifying customer data, or fetching
  real-time information, these tools make your AI more powerful and connected.
</Note>

## Overview

Custom Mid-Call Tools enable your AI assistant to:

* Make real-time API calls during conversations
* Fetch or submit data to your systems
* Make informed decisions based on live data
* Provide accurate, up-to-date information to callers

<Card title="Key Benefits" icon="star">
  - No coding required - just configure the API endpoint and parameters - AI
    automatically knows when and how to use the tools - Real-time data access
    during calls - Seamless integration with your existing systems
</Card>

<Info>
  Mid-call tools and [MCP servers](/ai-assistants/mcp-servers) both live under the
  **Mid call tools / MCP** page in the sidebar. Use a mid-call tool for a single
  HTTP endpoint you define by hand, and an MCP server to connect a remote server
  that exposes many tools at once.
</Info>

## Tool types

When you create a tool you choose one of two types:

<CardGroup>
  <Card title="HTTP request" icon="plug">
    Call **your own API** directly. You set the URL, method, headers, parameters
    and (optionally) a static body. Best when you already have an endpoint.
  </Card>

  <Card title="Automation Platform" icon="diagram-project">
    Autocalls **creates a linked flow for you** in the
    [Automation Platform](/automation-platform/introduction). The tool's endpoint
    is generated and locked automatically — you just build the logic in the flow
    and end with a **Return Response** step. Best for no-code, multi-step logic.
  </Card>
</CardGroup>

## Setting Up Your Tool

### 1. Basic Configuration

<Frame>
  <img alt="Main Tool Configuration" />
</Frame>

<Steps>
  <Step title="Access Tool Creation">
    Navigate to **Mid call tools** and click **Create Mid-Call Tool**
  </Step>

  <Step title="Configure Main Settings">
    Fill in the essential details:

    * **Name**: Letters, numbers and underscores, starting with a letter or underscore (up to **64 characters**, e.g., `check_order_status`)
    * **Description**: Explain when and how the AI should use this tool
    * **Endpoint**: Your API URL (e.g., `https://api.yourcompany.com/orders`)
    * **Timeout**: How long to wait for responses (1–30 seconds)
    * **Method**: Choose GET, POST, PUT, PATCH, or DELETE
    * **Body format**: For write methods (POST/PUT/PATCH), send the body as **JSON** (default) or **form-encoded** (`application/x-www-form-urlencoded`)
  </Step>

  <Step title="Add Headers">
    Common headers you might need:

    ```yaml theme={null}
    Content-Type: application/json
    Authorization: Bearer your_token
    ```
  </Step>
</Steps>

### 2. Variable Configuration

<Frame>
  <img alt="Variable Configuration" />
</Frame>

<Steps>
  <Step title="Define Parameters">
    These are the pieces of information your AI will collect during the call:

    ```yaml theme={null}
    Name: order_number
    Type: string
    Description: "10-digit order number from the customer"
    ```
  </Step>

  <Step title="Set Validation Rules">
    Add format requirements in the description:

    ```yaml theme={null}
    "Date in dd/mm/yyyy format"
    "Phone number without spaces"
    "Email address for confirmation"
    ```
  </Step>
</Steps>

## Understanding Parameter Types

<CardGroup>
  <Card title="String" icon="font">
    Text values like names, addresses, or reference numbers

    ```yaml theme={null}
    Type: string
    Examples: "John Doe", "123 Main St"
    ```
  </Card>

  <Card title="Number" icon="calculator">
    Whole numbers like quantities or IDs

    ```yaml theme={null}
    Type: number
    Examples: 42, 1500
    ```
  </Card>

  <Card title="Float" icon="calculator">
    Decimal numbers like prices or amounts

    ```yaml theme={null}
    Type: float
    Examples: 19.99, 4.5
    ```
  </Card>

  <Card title="Boolean" icon="toggle-on">
    True/false values for yes/no situations

    ```yaml theme={null}
    Type: boolean
    Examples: true, false
    ```
  </Card>
</CardGroup>

<Info>
  Each parameter can be marked **required** or optional. Optional parameters are
  only sent when the AI actually collected a value, so your endpoint won't receive
  empty fields. Add format hints in the description (e.g. `"Date in dd/mm/yyyy"`,
  `"Phone without spaces"`).
</Info>

## Static fields

Static fields are fixed key/value pairs that are **always sent** with every
request — the AI never changes them. Use them for constants like a tenant id, a
channel, or a source tag.

```yaml theme={null}
source: autocalls
tenant: acme
channel: sms
```

Static field **values** also support [system variables](#system-variables--dynamic-values)
(e.g. set `caller` to `{{customer_phone}}`).

## System variables & dynamic values

There are two ways to inject dynamic data into your tool:

<CardGroup>
  <Card title="AI-extracted parameters" icon="robot">
    Wrapped in **single braces** `{param}`. Replaced with the value the AI
    collected during the conversation. Used in the URL path/query.

    ```yaml theme={null}
    https://api.example.com/orders/{order_id}
    ```
  </Card>

  <Card title="System & account variables" icon="brackets-curly">
    Wrapped in **double braces** `{{variable}}`. Filled in automatically by the
    platform at call time. Usable in the **URL**, **header values**, and
    **static field values**.

    ```yaml theme={null}
    Authorization: Bearer {{crm_key}}
    ```
  </Card>
</CardGroup>

These system variables are injected automatically — no setup needed:

| Variable              | Value                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------- |
| `{{customer_phone}}`  | The other party's phone number (caller for inbound, callee for outbound). Empty on web/chat. |
| `{{assistant_phone}}` | The assistant's own phone number, if it has one.                                             |
| `{{assistant_id}}`    | The assistant's unique ID.                                                                   |
| `{{assistant_name}}`  | The assistant's name.                                                                        |
| `{{current_date}}`    | Current date in the assistant's timezone (e.g. `2026-06-15`).                                |
| `{{current_time}}`    | Current time in the assistant's timezone (e.g. `14:30`).                                     |

<Info>
  Any custom **account variables** you define are also available as `{{name}}` and
  can be used the same way.
</Info>

## Dynamic Endpoints

<Warning>
  When using variables in your endpoint URL, make sure to enclose them in curly
  braces and use the exact parameter name.
</Warning>

You can make your endpoints dynamic using variables:

```yaml theme={null}
Basic URL:
https://api.example.com/orders/status

With Variables:
https://api.example.com/orders/{order_id}/status
```

The AI will automatically replace `{order_id}` with the actual value collected during the conversation.

## Testing Made Easy

<Card title="Automatic Testing" icon="vial">
  Click **Test tool** to fire a real request with realistic sample data:

  * **String** parameters: `"Sample data"`
  * **Number** parameters: `42`
  * **Float** parameters: `19.99`
  * **Boolean** parameters: `true`
  * **System variables** like `{{customer_phone}}` are filled with realistic placeholders (e.g. `+1234567890`, the assistant name/id)

  You'll see the request data, response code and body, helping you verify everything
  works before going live.
</Card>

<Note>
  Automation Platform tools don't have a **Test tool** button — you test them by
  running the linked flow inside the Automation Platform.
</Note>

## Automation Platform tools

<Note>
  Need more complex logic? Create an **Automation Platform** tool and Autocalls
  builds and links the flow for you — no manual webhook setup required.
</Note>

When you set the tool type to **Automation Platform**, Autocalls automatically
creates a connected flow in the [Automation Platform](/automation-platform/introduction)
and wires the tool's endpoint to it. The endpoint and method are **generated and
locked**, so they can't accidentally be changed.

<Steps>
  <Step title="Create the tool">
    Choose the **Automation Platform** type, give the tool a name, description and
    parameters. On save, the linked flow is created automatically.
  </Step>

  <Step title="Open the flow">
    On the tool's edit page, the connection card shows the flow status
    (**Live**/**Disabled**) and an **Open flow in Automation Platform** button.
    The flow starts from a webhook trigger and ends with a **Return Response**
    step.
  </Step>

  <Step title="Build your logic">
    Add steps between the trigger and the response — API calls, CRM updates,
    branching, data transforms — then keep a **Return Response** step so the AI
    receives a result.
  </Step>

  <Step title="Keep parameters in sync">
    If you change the tool's parameters or static fields, use **Resync sample
    data** so the flow's trigger sample matches. If the initial flow creation ever
    fails, a **Retry flow creation** button appears on the edit page.
  </Step>
</Steps>

This lets you:

* Transform data before/after API calls
* Make multiple API calls in sequence
* Apply complex business logic
* Handle errors gracefully

<Tip>
  Prefer to wire it up yourself? You can still use a plain **HTTP request** tool
  pointed at an existing Automation Platform webhook URL with `/sync` appended
  (e.g. `https://automate.autocalls.ai/api/v1/webhooks/abc123/sync`).
</Tip>

## Real-World Examples

<AccordionGroup>
  <Accordion title="Order Lookup System" icon="magnifying-glass">
    ```yaml theme={null}
    Name: check_order
    Endpoint: https://api.yourshop.com/orders/{order_number}
    Parameters:
      - Name: order_number
        Type: string
        Description: "Order reference (format: ORD-XXXXX)"
    ```

    The AI will:

    1. Ask for the order number
    2. Fetch the status
    3. Explain delivery dates and status to the customer
  </Accordion>

  <Accordion title="Appointment Availability" icon="calendar">
    ```yaml theme={null}
    Name: check_slots
    Endpoint: https://api.calendar.com/availability
    Parameters:
      - Name: service
        Type: string
        Description: "Service type (haircut, massage, consultation)"
      - Name: date
        Type: string
        Description: "Preferred date (dd/mm/yyyy)"
    ```

    The AI will:

    1. Ask about the desired service
    2. Get preferred date
    3. Show available time slots
  </Accordion>

  <Accordion title="Customer Verification" icon="shield-check">
    ```yaml theme={null}
    Name: verify_customer
    Endpoint: https://api.crm.com/verify
    Parameters:
      - Name: phone
        Type: string
        Description: "10-digit phone number"
      - Name: email
        Type: string
        Description: "Email address for verification"
    ```

    The AI will:

    1. Collect contact details
    2. Verify against your CRM
    3. Proceed based on verification status
  </Accordion>
</AccordionGroup>

## Configuring Your AI

<Info>
  The AI needs clear instructions in its system prompt to effectively use your
  custom tools.
</Info>

Example prompt section:

```yaml theme={null}
When to use check_order tool:
1. Customer asks about order status
2. Mentions tracking or delivery
3. Wants to know where their package is

How to use it:
1. Ask for order number if not provided
2. Verify format (ORD-XXXXX)
3. Use tool to fetch status
4. Explain results in simple terms
```

<Tip>
  Test your tools with various conversation flows to ensure the AI handles all
  scenarios smoothly. Start with simple test calls before going live.
</Tip>


# Filler Audio
Source: https://docs.autocalls.ai/ai-assistants/filler-audio

Learn how to use filler audio to create more natural conversations with your AI assistant

Filler audio adds natural conversation sounds (like "hmm" or "one moment") while your AI assistant processes responses. This creates a more human-like interaction by eliminating awkward silences.

## How It Works

When enabled, your AI assistant will:

* Use short audio fillers during processing time
* Maintain engagement while formulating responses
* Signal active listening to the caller

## Benefits

1. **Improved Conversation Flow**

   * Eliminates dead air
   * Keeps callers engaged
   * Reduces hang-ups
   * Creates natural dialogue rhythm

2. **Enhanced User Experience**
   * More human-like interaction
   * Less awkward waiting
   * Better caller retention
   * Increased trust

## Setup

1. Go to your [AI assistant settings](/ai-assistants/settings/general#audio-enhancement-settings)
2. Find the "Filler Audio" option
3. Toggle it on
4. Save your changes

## Best Practices

### Combine with Fast Engine

* Use filler audio with the Fast Engine setting
* Creates the most natural conversation flow
* Minimizes perceived response time

### Use Cases

* **Sales Calls**: Keep prospects engaged
* **Customer Service**: Show active listening
* **Lead Qualification**: Maintain natural flow

## Testing

After enabling filler audio:

1. Make a test call
2. Listen for natural transition sounds
3. Verify timing and appropriateness
4. Adjust if needed

***

**Tip:** Start with filler audio enabled - you can always disable it if it doesn't suit your use case.


# Flow Builder
Source: https://docs.autocalls.ai/ai-assistants/flow-builder

Design conversation flows visually with an intuitive drag-and-drop interface

Flow Builder is a visual, drag-and-drop conversation flow editor that lets you design AI assistant scripts without writing code. Create multi-step conversation flows by connecting nodes that represent different actions and decision points.

## Overview

Flow Builder provides:

* **Visual design** - Drag-and-drop nodes on a canvas
* **Multiple node types** - Messages, prompts, actions, and more
* **Branching logic** - Create different paths based on responses
* **Settings panel** - Configure agent personality and behavior
* **Import/Export** - Save and share flows as JSON files

<Frame>
  <img alt="Flow Builder Interface" />
</Frame>

## When to Use Flow Builder

<CardGroup>
  <Card title="Use Flow Builder for" icon="check">
    * Structured conversation scripts
    * Multi-path decision trees
    * Complex call flows with branches
    * Visual thinkers who prefer diagrams
  </Card>

  <Card title="Use Classic Editor for" icon="pen">
    * Simple, linear conversations
    * Highly dynamic AI responses
    * Quick prompt iterations
    * Text-focused editing
  </Card>
</CardGroup>

## Getting Started

<Steps>
  <Step title="Open your assistant">
    Navigate to **Assistants** and click on the assistant you want to edit.
  </Step>

  <Step title="Find Flow Builder">
    In the edit form, scroll to the **System Prompt** section and click the **Flow Builder** tab.
  </Step>

  <Step title="Launch Flow Builder">
    Click **Launch Flow Builder**. A full-screen editor will open.
  </Step>

  <Step title="Choose how to start">
    * **Continue with existing** - Edit your current flow
    * **Start from scratch** - Begin with just a Start node
    * **Start with template** - Load a pre-built flow template
  </Step>
</Steps>

## Interface Overview

### Canvas Area (Center)

The main workspace where you build your flow:

* **Nodes** - Drag to reposition
* **Connections** - Lines showing flow between nodes
* **Grid background** - Helps with alignment
* **Zoom controls** - Zoom in/out and fit to view
* **Pan** - Click and drag on empty space to move around

### Bottom Toolbar

Quick actions for managing your flow:

| Button         | Action                             |
| -------------- | ---------------------------------- |
| ⚡ Auto Layout  | Automatically arrange nodes neatly |
| 📋 Duplicate   | Copy selected node                 |
| 🗑️ Delete     | Remove selected node or connection |
| **+ Add Node** | Add a new node to the canvas       |

### Settings Panel (Right Side)

Configure your assistant's personality and behavior:

* **Agent Name** - The name your AI will use
* **Agent Type** - Sales, Support, Survey, etc.
* **Language** - Spoken language for calls
* **Assertiveness** - How pushy the AI should be
* **Humor** - Level of humor in responses
* **Variables** - Pre-call data fields
* **Post-Call Fields** - Data to collect after calls

## Node Types

Flow Builder has 5 node types, each with a specific purpose:

<Frame>
  <img alt="Flow Builder Node Types" />
</Frame>

### Start Node (Green)

<Card title="Start Node" icon="play">
  The entry point of every conversation. Every flow must have exactly one Start node.

  **Properties:**

  * **Greeting** - The initial message when the call begins

  **Example:** "Hi, this is Sarah from Acme Insurance. How are you today?"
</Card>

### Speak Node (Blue)

<Card title="Speak Node" icon="volume-high">
  Delivers a pre-written message exactly as specified. Use when you need precise wording.

  **Properties:**

  * **Text** - The exact message to speak
  * **Outcomes** - Different paths based on customer response

  **Example:** "We're offering a limited-time 20% discount on all plans. Would you like to hear more?"
</Card>

### Prompt Node (Purple)

<Card title="Prompt Node" icon="message">
  Gives the AI instructions on how to respond. More flexible than Speak nodes - the AI generates contextual responses.

  **Properties:**

  * **Prompt** - Instructions for the AI
  * **Outcomes** - Different paths based on response categories

  **Example prompt:** "Ask the customer about their current insurance coverage. Be conversational and empathetic. Listen for mentions of their family size, budget concerns, or timeline."
</Card>

### Action Node (Orange)

<Card title="Action Node" icon="bolt">
  Executes special actions during the call.

  **Action Types:**

  * **Call Forward** - Transfer to another number
  * **Book Appointment** - Schedule using connected calendar
  * **Custom Action** - Trigger a custom mid-call tool

  **Example:** Forward to sales team at +1-555-123-4567 when customer is ready to purchase.
</Card>

### End Node (Red)

<Card title="End Node" icon="phone-slash">
  Terminates the call or transfers to another destination.

  **End Types:**

  * **End Call** - Hang up with a closing message
  * **Forward Call** - Transfer to a phone number
  * **Transfer Agent** - Hand off to another assistant

  **Example closing:** "Thank you for your time today. Have a great day!"
</Card>

## Working with Nodes

### Adding Nodes

1. Click **+ Add Node** in the bottom toolbar
2. Select the node type from the dropdown
3. The node appears on the canvas
4. Drag it to your desired position

### Connecting Nodes

1. Hover over a node's bottom edge to see the **output handle** (small circle)
2. Click and drag from the output handle
3. Connect to another node's **input handle** (top edge)
4. Release to create the connection

### Editing Nodes

1. Click on any node to select it
2. The node's properties appear in a panel
3. Edit the text, prompt, or settings
4. Changes save automatically to the canvas

### Deleting Nodes

* Select a node and press **Delete** key, or
* Select a node and click the 🗑️ button in the toolbar

<Warning>
  The Start node cannot be deleted. Every flow must have one Start node.
</Warning>

## Outcomes (Multiple Paths)

Speak and Prompt nodes can have multiple **outcomes** - different paths based on how the customer responds.

### Adding Outcomes

1. Select a Speak or Prompt node
2. In the properties panel, find **Outcomes**
3. Click **Add Outcome**
4. Name the outcome (e.g., "Interested", "Not interested", "Wants callback")

### Connecting Outcomes

Each outcome appears as a colored dot at the bottom of the node. Connect each outcome to a different destination node to create branching logic.

<Frame>
  <img alt="Conversation Branching with Outcomes" />
</Frame>

**Example flow:**

```
[Start] → [Ask about interest]
              ↓
         [Prompt: "Ask if interested"]
              ↓
    ┌─────────┼─────────┐
    ↓         ↓         ↓
[Interested] [Maybe] [Not Interested]
    ↓         ↓         ↓
[Book Demo] [Send Info] [Thank & End]
```

## Settings Panel

<Frame>
  <img alt="Flow Builder Settings Panel" />
</Frame>

### Agent Identity

| Setting        | Description                                      |
| -------------- | ------------------------------------------------ |
| **Agent Name** | Name the AI uses to introduce itself             |
| **Agent Type** | Preset personality: Sales, Support, Survey, etc. |
| **Language**   | Primary language for the conversation            |

### Personality

| Setting           | Options                   | Description                 |
| ----------------- | ------------------------- | --------------------------- |
| **Assertiveness** | Low / Medium / High       | How persistent the AI is    |
| **Humor**         | Off / Low / Medium / High | Level of humor in responses |

### Variables

Add pre-call data that can be used in your messages:

1. Click **Add Variable**
2. Enter a **Name** (e.g., `product_interest`)
3. Set a **Default Value**

Use variables in messages with curly braces: `{variable_name}`

**Example:** "Hi , I see you were interested in our ."

### Post-Call Fields

Define data to extract from calls:

1. Click **Add Field**
2. Enter **Name**, **Type**, and **Description**
3. The AI will attempt to fill these based on the conversation

**Types:** `string`, `number`, `boolean`

## Import/Export

### Export Your Flow

1. Open the Settings panel
2. Scroll to the bottom
3. Click **Export JSON**
4. Save the `.json` file

### Import a Flow

1. Click **Import JSON** in settings
2. Select your `.json` file
3. The flow loads on the canvas

<Tip>
  Export your flows regularly as backups. You can also share flows with team members this way.
</Tip>

## Voicemail Settings

Configure what happens when voicemail is detected:

* **Voicemail Message** - Message to leave if voicemail answers
* **End Call on Voicemail** - Toggle to automatically hang up on voicemail

## Saving Your Flow

Click the **Save** button in the top-right corner to save your flow to the assistant.

<Note>
  The flow is stored as JSON in your assistant's system prompt field. If you switch to the Classic Editor, you'll see the raw JSON data.
</Note>

## Best Practices

<CardGroup>
  <Card title="Start Simple" icon="seedling">
    Begin with a basic flow and add complexity gradually. Test at each step.
  </Card>

  <Card title="Use Prompt Nodes" icon="brain">
    Prompt nodes give the AI flexibility. Use them for dynamic, context-aware responses.
  </Card>

  <Card title="Plan Your Outcomes" icon="diagram-project">
    Before building, sketch the main paths: positive, negative, and neutral responses.
  </Card>

  <Card title="Test Thoroughly" icon="vial">
    Make test calls covering all paths. Verify each outcome leads to the right destination.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Nodes won't connect">
    * Ensure you're dragging from an **output handle** (bottom) to an **input handle** (top)
    * Check that you're not creating a circular connection
    * The Start node only has an output, End node only has an input
  </Accordion>

  <Accordion title="Flow not saving">
    * Check your internet connection
    * Ensure you have at least one node (besides Start)
    * Look for any validation errors in the settings panel
  </Accordion>

  <Accordion title="AI not following the flow">
    * Use Speak nodes for exact wording requirements
    * Make Prompt node instructions more specific
    * Check that outcomes are clearly defined and connected
  </Accordion>
</AccordionGroup>

## Related Resources

* [AI Prompt Editor](/ai-assistants/ai-prompt-editor) - Chat-based alternative for prompt editing
* [System Prompts Guide](/ai-assistants/system-prompt) - Understanding prompt fundamentals
* [Testing Your Assistant](/ai-assistants/testing) - How to test your flows


# GoHighLevel Appointment Scheduling
Source: https://docs.autocalls.ai/ai-assistants/gohighlevel-scheduling

Learn how to enable your AI assistant to schedule appointments using GoHighLevel integration

Enable your AI assistant to seamlessly schedule meetings and appointments using GoHighLevel integration. This powerful feature allows your AI to check availability and book meetings directly during calls with your existing GoHighLevel calendar system.

## Prerequisites

Before setting up GoHighLevel integration, you'll need:

* An active GoHighLevel account
* Calendar(s) configured in your GoHighLevel location
* Admin or appropriate permissions to authorize app connections

## Setup Process

### 1. GoHighLevel Account Requirements

**Account Setup:**

* Ensure you have an active GoHighLevel account
* Verify that your calendars are properly set up in your account
* Confirm you have the necessary permissions to connect external applications

**Calendar Configuration:**

* Create or verify existing calendars in your GoHighLevel location
* Set appropriate availability times and booking settings
* Configure any required custom fields for appointments

### 2. Connecting GoHighLevel to Your Assistant

1. In your [AI assistant settings](/ai-assistants/settings/prompt-and-tools#default-tools), navigate to the **Tools** section
2. Select **Appointment Scheduling** from the available tools
3. Choose **GoHighLevel** as your calendar integration type
4. Click **Connect to GoHighLevel**

**OAuth Authorization Process:**

1. You'll be redirected to GoHighLevel's authorization page
2. **Choose your account** from the available options
3. **Authorize the application** to access your calendar data
4. You'll be redirected back to your assistant settings

<Note>
  If you have issues connecting to GoHighLevel, try using an **Incognito/Private browsing window** as this can resolve authentication conflicts.
</Note>

### 3. Calendar Selection

After successful connection:

1. Select the specific **calendar** from your GoHighLevel location
2. Your available calendars will be automatically fetched and displayed
3. Choose the calendar where appointments should be booked

### 4. Testing the Integration

**Essential testing steps:**

1. Make a test call to your AI assistant
2. Request to schedule an appointment during the conversation
3. Verify the booking appears in your GoHighLevel calendar
4. Check that confirmation details are sent appropriately
5. Test different scenarios (available/unavailable times)

## Required Information from GoHighLevel

To complete the integration, the system needs access to:

### From Your GoHighLevel Account:

* **Location ID:** Automatically obtained during OAuth authorization
* **Calendar IDs:** Retrieved from your location's available calendars
* **Access Tokens:** Managed automatically through OAuth flow

### Calendar Permissions:

* **Read calendar availability:** To check open time slots
* **Create appointments:** To book new meetings
* **Access calendar details:** To retrieve calendar names and settings

## Integration Features

### Automatic Appointment Booking

* **Real-time availability checking:** AI verifies open time slots
* **Instant booking confirmation:** Appointments created immediately in GoHighLevel
* **Conflict prevention:** System prevents double-booking
* **Time zone handling:** Respects calendar and customer time zones

### Email Requirement for Appointments

**Important:** To book appointments, your AI assistant needs an email address from the customer.

**Setup options:**

1. **Define email in input variables:** Add `email` as an input variable in your [assistant settings](/ai-assistants/settings/prompt-and-tools#call-variables)
2. **Import leads with email:** When importing leads, ensure email addresses are included
3. **AI collection during call:** Configure your assistant to ask for email during the conversation if not available

**Example prompt instruction:**

```
"If the customer wants to book an appointment and I don't have their email address, 
ask them to provide their email address for the booking confirmation."
```

## Best Practices

### Calendar Management

* **Keep calendars updated:** Ensure availability is current in GoHighLevel
* **Set buffer times:** Configure appropriate gaps between appointments
* **Use clear calendar names:** Makes selection easier during setup

### Assistant Configuration

* **Include calendar context in system prompt:** Help AI understand booking scenarios
* **Define appointment variables:** Extract relevant information for GoHighLevel
* **Configure appointment duration:** Specify how long appointments should be

**Appointment Duration Setup:**
Tell your AI assistant about appointment lengths in the system prompt:

```
"When booking appointments, use 45-minute slots. If a customer says they want 
to meet at 8:00 AM, set the end_time to 8:45 AM. Always calculate the end_time 
based on the start time plus 45 minutes."
```

**Example scenarios:**

* Customer says: "Can we meet at 2:00 PM?"

* AI books: 2:00 PM - 2:45 PM (45-minute slot)

* **Test various scenarios:** Different time requests, conflicts, rescheduling

### Security & Compliance

* **Token management:** OAuth tokens are refreshed automatically
* **Data privacy:** Only necessary calendar data is accessed
* **Permission scope:** Integration uses minimal required permissions

## Troubleshooting

### Quick Fixes:

**Missing API Key Error:**

* **Solution:** Disconnect and reconnect your GoHighLevel account, then select an assistant and save
* **Steps:** Go to [assistant settings](/ai-assistants/settings/prompt-and-tools#default-tools) → Appointment Scheduling → Disconnect → Connect again → Select assistant → Save

**Connection Issues:**

* **Try incognito mode** for OAuth authorization
* **Verify account permissions** and calendar setup

**Calendar Problems:**

* **Refresh connection** if calendars don't appear
* **Check time zones** and availability settings

<Note>
  For comprehensive GoHighLevel troubleshooting, including detailed solutions and additional issues, see [GoHighLevel Issues](/troubleshooting/gohighlevel).
</Note>


# Initial Message & Audio
Source: https://docs.autocalls.ai/ai-assistants/initial-message

Learn how to create effective initial messages and use custom audio files for the best first impression

The first few seconds of a call are crucial - they determine whether the customer stays on the line. You have two options for your assistant's first greeting: text-based initial message or custom initial audio.

## Initial Message

This is the first thing your AI assistant says when starting a call. The message is read exactly as written, so:

### Best Practices

1. **Keep it Short**

   * Aim for 5-10 seconds
   * Get to the point quickly
   * Avoid long company introductions

2. **Write Exactly as Needed**

   * Include proper diacritics (é, ñ, ü, etc.)
   * Use punctuation for proper pausing
   * Write numbers as they should be spoken

3. **Example Formats**

   ```
   Good:
   "Hi! This is Sarah from ABC Company. How can I help you today?"

   Better with pausing:
   "Hi! This is Sarah from ABC Company... How can I help you today?"

   With diacritics:
   "¡Hola! Soy María de ABC Company. ¿Cómo puedo ayudarte?"
   ```

## Initial Audio

For the best first impression, you can use a pre-recorded audio file:

### Benefits

* Professional quality
* Perfect pronunciation
* Human warmth
* Consistent delivery
* Higher customer retention

### Setup Process

1. Record your greeting with a professional voice actor
2. Upload the audio file in [assistant settings](/ai-assistants/settings/general#call-flow-configuration)
3. Clone the same voice for the rest of the conversation
4. Enable initial audio playback

### Best Practices

1. **Recording Quality**

   * Use professional equipment
   * Record in a quiet environment
   * Maintain consistent volume
   * Save in high quality format

2. **Voice Matching**

   * Use the same voice actor for cloning
   * Maintain consistent tone and style
   * Match energy levels

3. **Content Guidelines**
   * Keep under 10 seconds
   * Include company name
   * State purpose clearly
   * Sound welcoming

### Example Script Structure

```
[Greeting] + [Company Name] + [Purpose/Question]

"Hello! This is ABC Company calling about your recent inquiry. How are you today?"
```

## Combining Both Methods

You can set up both:

* Initial audio as primary greeting
* Initial message as backup
* System will use audio when available

## Testing

Before going live:

1. Call your assistant
2. Listen for:
   * Clear pronunciation
   * Natural pauses
   * Proper volume
   * Smooth transition to AI conversation

## Language Considerations

* Each language needs its own initial message/audio
* Use native speakers for recordings
* Consider regional accents
* Test with target audience

***

**Pro Tip:** Record several versions of your initial audio and test which one gets better response rates.


# MCP Servers
Source: https://docs.autocalls.ai/ai-assistants/mcp-servers

Connect remote Model Context Protocol (MCP) servers so your AI assistant can use external tools during voice and chat conversations

<Note>
  MCP servers let your AI assistant pull live data and trigger actions in
  external systems — like HubSpot, your internal APIs, or knowledge tools —
  right in the middle of a conversation. Connect a server once, assign it to any
  assistant, and its tools become available to the AI automatically.
</Note>

## What is an MCP server?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open
standard for exposing tools to AI models. An **MCP server** is simply a remote
HTTP endpoint that speaks this protocol. You don't install anything — you paste
the server's URL (and optional authentication headers), and the assistant can
call its tools while talking to your customer.

<Card title="Why use MCP servers?" icon="bolt">
  * Add whole toolsets (e.g. a HubSpot or Notion integration) in one step instead of building tools one by one
  * Tools, descriptions and parameters are discovered automatically from the server
  * Works across voice calls, the web widget, and chat
  * Reuse one server across many assistants
</Card>

## Mid-call tools vs. MCP servers

Both live under the **Tools** page. Use whichever fits:

<CardGroup>
  <Card title="Mid-call tools" icon="plug">
    A single custom HTTP endpoint you define by hand (URL, method, parameters).
    Best for one-off calls to your own API. See [Custom Mid-Call Tools](/ai-assistants/custom-tools).
  </Card>

  <Card title="MCP servers" icon="share-nodes">
    A remote server that exposes **many** tools at once, discovered
    automatically. Best for connecting to a platform or a shared integration.
  </Card>
</CardGroup>

## Connecting a server

<Frame>
  <img alt="MCP server configuration form" />
</Frame>

<Steps>
  <Step title="Open the Tools page">
    Go to **Tools** in the sidebar and switch to the **MCP servers** tab, then click **New MCP server**.
  </Step>

  <Step title="Fill in the details">
    * **Display name**: a friendly name shown when assigning the server (e.g. `HubSpot CRM`)
    * **Identifier**: an internal id, lowercase letters and underscores only (e.g. `hubspot`)
    * **Description**: optional, for your own reference
    * **Server URL**: the remote MCP endpoint
    * **Timeout**: how long to wait when connecting to the server
  </Step>

  <Step title="Choose the transport">
    Leave this on **Auto-detect** unless you know otherwise. Auto-detect picks the
    right transport from the URL:

    ```yaml theme={null}
    URL ends with /mcp  →  Streamable HTTP
    URL ends with /sse  →  SSE (Server-Sent Events)
    ```
  </Step>

  <Step title="Add authentication headers (optional)">
    If the server requires a token, add it as a header. Headers are **stored encrypted**.

    ```yaml theme={null}
    Authorization: Bearer your_token_here
    ```
  </Step>
</Steps>

When you save, the server is tested automatically and a notification lists the
tools it exposes.

### Try it for free

<Tip>
  Want to test MCP without any setup? Connect the public **DeepWiki** server (no
  authentication required):

  * **Display name**: `DeepWiki`
  * **Identifier**: `deepwiki`
  * **Server URL**: `https://mcp.deepwiki.com/mcp`

  Then ask your assistant something like *"Use DeepWiki to summarize the
  facebook/react repository."*
</Tip>

## Connection status & discovered tools

Each server is shown as a card with a live connection status.

<Frame>
  <img alt="MCP servers list with connection status and discovered tools" />
</Frame>

<CardGroup>
  <Card title="Connected" icon="circle-check">
    The server is reachable. Its available tools are listed on the card.
  </Card>

  <Card title="Disconnected" icon="circle-exclamation">
    The server couldn't be reached. The error is shown so you can fix the URL or headers.
  </Card>

  <Card title="Not tested" icon="circle-question">
    The server hasn't been checked yet.
  </Card>
</CardGroup>

Use **Test connection** at any time to re-check a server and refresh its tool list.

## Choosing which tools are exposed

By default, **all** of a server's tools are available to your assistants. Open
**Manage tools** (on the server's edit page) to view each tool's description and
parameters, and enable or disable individual tools.

<Frame>
  <img alt="Manage tools panel showing tool descriptions, parameters and enable/disable toggles" />
</Frame>

<Info>
  Disabled tools are hidden from the AI. To expose **no** tools at all, simply
  remove the server from the assistant instead.
</Info>

## Assigning a server to an assistant

<Steps>
  <Step title="Open your assistant">
    Edit an assistant and go to the **Prompt & Tools** step.
  </Step>

  <Step title="Assign MCP servers">
    In the **MCP servers** section, select one or more servers. The list shows
    each server's connection status and tool count.
  </Step>

  <Step title="Save">
    The assistant can now use the server's enabled tools during voice calls, the
    web widget, and chat.
  </Step>
</Steps>

## Authentication

The integration sends **static headers** with each request. It does not perform
an interactive OAuth login.

| Server authentication                             | Supported | How                                             |
| ------------------------------------------------- | --------- | ----------------------------------------------- |
| No authentication                                 | ✅         | Nothing to configure                            |
| API key / token                                   | ✅         | Add an `Authorization` (or custom) header       |
| Token embedded in the URL (e.g. Zapier, Composio) | ✅         | Paste the full URL                              |
| Interactive OAuth login                           | ❌         | Use a personal access token in a header instead |

## Real-world examples

<AccordionGroup>
  <Accordion title="Documentation lookup (DeepWiki)" icon="book">
    ```yaml theme={null}
    Display name: DeepWiki
    Identifier: deepwiki
    Server URL: https://mcp.deepwiki.com/mcp
    Headers: (none)
    Tools: read_wiki_structure, read_wiki_contents, ask_question
    ```

    The assistant can answer questions about any public GitHub repository.
  </Accordion>

  <Accordion title="CRM access (HubSpot-style)" icon="address-book">
    ```yaml theme={null}
    Display name: HubSpot CRM
    Identifier: hubspot
    Server URL: https://your-mcp-host.example.com/mcp
    Headers:
      Authorization: Bearer pat-xxxxxxxx
    ```

    The assistant can look up contacts, create deals, or update records during a call.
  </Accordion>
</AccordionGroup>

## Best practices & security

<Warning>
  Only connect MCP servers you trust. The tools and the data they return are
  provided by the remote server and are passed to the AI during live
  conversations.
</Warning>

* Keep tokens scoped to the minimum permissions the assistant needs.
* Use **Manage tools** to expose only the tools an assistant actually requires.
* Give each tool a clear name and description on the server so the AI knows when to use it.
* Mention the available capabilities in your assistant's [system prompt](/ai-assistants/system-prompt) so it uses them at the right moments.

<Tip>
  Test with simple conversations first and confirm the assistant calls the right
  tool with the right parameters before going live.
</Tip>


# General Settings
Source: https://docs.autocalls.ai/ai-assistants/settings/general

Basic configuration settings for your AI assistant including call direction, phone numbers, voice, and advanced settings.

Configure the fundamental settings for your AI assistant including call direction, phone numbers, voice selection, and technical parameters.

## Quick Start Guide

Ready to set up your first AI assistant? Here's the essential flow:

1. **Choose Call Direction:** Inbound (answers calls) or Outbound (makes calls)
2. **Set Assistant Name:** Internal label like "Support Bot" or "Sales Bot"
3. **Configure Phone Numbers:** Assign platform numbers, SIP, or Caller ID
4. **Select Voice & Language:** Choose from built-in voices or clone custom ones
5. **Adjust Advanced Settings:** Fine-tune models, timing, and audio parameters

<Tip>
  **Always test your changes** by calling the assistant or running a small campaign to confirm it behaves as expected.
</Tip>

<Note>
  Follow this page section by section to configure your assistant. Each setting includes detailed explanations and best practices to help you make the right choices.
</Note>

## Call Direction & Basic Setup

### Assistant Type

Choose whether your assistant handles **inbound** or **outbound** calls. This fundamental choice affects which other options become available.

**Inbound (Receive calls):** Handles incoming calls from customers. See [Inbound calls overview](/inbound-calls/overview).

**Outbound (Make calls):** Initiates calls to leads or customers. See [Outbound calls overview](/outbound-calls/overview).

### Assistant Name

A descriptive name to identify your assistant in the dashboard. Use something memorable that describes the assistant's purpose (e.g. "Sales Qualifier", "Support Bot", "Appointment Scheduler").

## Phone Number Configuration

Your assistant needs a phone number to operate. The available options depend on your call direction choice.

### For Outbound Assistants

You can use:

* **Platform numbers:** Numbers rented directly from our platform
* **SIP numbers:** Connect your existing VOIP/PBX system
* **Caller ID only:** Verify ownership of an existing number to display it on outbound calls

### For Inbound Assistants

You can use:

* **Platform numbers:** Numbers rented directly from our platform
* **SIP numbers:** Connect your existing VOIP/PBX system

**Note:** Caller ID only numbers cannot handle inbound calls - they only display on outbound calls.

### Pricing & Costs

* **Platform numbers:** Monthly rental fees starting from \$3.99/month. See [renting a dedicated number](/pricing/number-rentals#1-renting-a-dedicated-number) for detailed pricing.
* **SIP integration:** No monthly fee, only \$0.00045/min for AI bridging. See [SIP integration pricing](/pricing/number-rentals#2-sip-integration-no-monthly-fee).
* **Caller ID:** No monthly fee, region-based per-minute rates (e.g., \$0.01/min in the US). See [Caller ID pricing](/pricing/number-rentals#3-caller-id-no-monthly-fee).

See [Phone number types](/phone-numbers/types) for detailed explanations and [SIP integration guide](/provisioning/sip-trunking/sip-integration) for VOIP setup.

## Engine Type (Voice Processing Mode)

Choose how your AI processes speech and generates responses. Each mode is optimized for different use cases. See [Assistant modes](/ai-assistants/assistant-modes) for detailed comparisons.

### Pipeline Mode

Traditional Speech-to-Text → LLM → Text-to-Speech pipeline. Offers maximum control over voice selection and response generation.

**Best for:** Complex reasoning, function calling, custom voice requirements

### Speech-to-Speech Mode

Direct speech-to-speech generation without intermediate text processing. Provides the most natural conversational flow.

**Best for:** Quick conversations, natural back-and-forth dialogue

### Dualplex Mode (Beta)

Combines fast multimodal processing with premium ElevenLabs voice output.

**Best for:** Most use cases - recommended default

## Language Configuration

### Primary Language

The main language your assistant will use for speech recognition and synthesis. This affects:

* Speech recognition accuracy
* Available voice options
* Filler audio phrases
* Voice model selection

See [Language support](/conversation-design/language-support) for all available languages and accents.

### Secondary Languages

Additional languages your assistant can understand and speak. Useful for:

* Multilingual customer support
* International businesses
* Code-switching conversations

**Note:** The AI can detect which language the customer is speaking and respond appropriately.

## TTS Provider & Voice Selection

### TTS Provider

Select your Text-to-Speech provider. Available in **Pipeline** and **Dualplex** modes.

**Available Providers:**

* **ElevenLabs** - High-quality voices
* **Cartesia** - Fast, low-latency synthesis

Your assistant can choose from existing voices, clone custom voices, or request voices from the ElevenLabs library.

### Voice Options

You have three ways to get the perfect voice for your assistant:

**1. Choose from existing voices:**

* **Professional voices:** Pre-trained, high-quality options from ElevenLabs
* **Multiple accents:** Available for most languages
* **Gender options:** Male and female voices for each language
* **Tone variety:** From formal business to casual conversational

**2. Clone a custom voice:**
Create a custom voice by uploading audio samples. Available in **Pipeline** and **Dualplex** modes.

**Requirements by provider:**

* **Cartesia** - Single audio file, at least 10 seconds, 1 speaker, no background noise
* **ElevenLabs** - Samples over 1 minute, 1 speaker, no background noise. Max 5 minutes total.

**Process:**

1. Click "Clone voice" next to voice selector
2. Select provider (Cartesia or ElevenLabs)
3. Choose the voice language
4. Enter a name for your voice
5. Record or upload audio
6. Wait for processing
7. Select your new voice from dropdown

**Use cases:**

* Brand consistency with company spokesperson
* Personal touch for customer relationships
* Matching voice to specific business persona

**3. Request from ElevenLabs library:**
You can request specific voices from the ElevenLabs public library - contact support to add them to your account. Browse the [ElevenLabs Voice Library](https://elevenlabs.io/docs/product-guides/voices/voice-library) to discover thousands of professional voices across different languages, accents, and use cases.

See [Voice selection guide](/ai-assistants/voice-selection) for detailed setup instructions.

## Timezone Configuration

### Timezone

Set the timezone your assistant operates in. This affects:

* Time-based variables in conversations
* Appointment scheduling functions
* "Current time" references in system prompts
* Timestamps in call logs and data extraction

**Important:** Choose the timezone where your business operates or where most customers are located. The assistant will use this for any time-related calculations or scheduling.

## Audio Enhancement Settings

### Ambient Sound

Optional background sound mixed under your assistant's voice to mask processing delays and create a more natural audio experience.

**Options:**

* **None:** No background sound (default)
* **Office:** Subtle office environment sounds

**Volume control:** Adjust the level of ambient sound relative to the voice. Lower values are usually better - too much background sound can interfere with speech recognition.

<Tip>
  Turn off or lower volume if the assistant isn't hearing the customer clearly.
</Tip>

### Filler Audio

Short conversational phrases like "mhm", "okay", "I understand" that play during AI processing time. See [Filler audio guide](/ai-assistants/filler-audio) for full details.

<Card title="Benefits" icon="star">
  * Eliminates awkward silences during processing
  * Keeps callers engaged
  * Creates more natural conversation flow
  * Reduces hang-up rates
</Card>

**Language-aware configuration:** Filler phrases are automatically set for your selected language:

<AccordionGroup>
  <Accordion title="Positive responses" icon="thumbs-up">
    "Great!", "Perfect!", "Super!"
  </Accordion>

  <Accordion title="Negative responses" icon="thumbs-down">
    "Hmm.", "I see.", "Okay."
  </Accordion>

  <Accordion title="Question responses" icon="circle-question">
    "Right?", "Really?", "How so?"
  </Accordion>

  <Accordion title="Neutral responses" icon="circle">
    "Okay.", "I understand.", "Got it."
  </Accordion>
</AccordionGroup>

**Customization:** You can edit the default phrases for each category to match your brand voice or regional preferences.

<Note>
  Enable by default - most conversations benefit from fillers. Test with your target audience and adjust phrases to match your assistant's personality.
</Note>

## Advanced Settings

### LLM Model Selection

Choose the best language model for your assistant's mode. See [LLM model selection guide](/ai-assistants/assistant-configuration#3-select-an-llm-model) for detailed recommendations.

**Recommended models by mode:**

| Model                    | Strengths                                     | Best for                                |
| ------------------------ | --------------------------------------------- | --------------------------------------- |
| **GPT-5 Mini**           | Balanced reasoning with low latency           | **Pipeline** mode for complex reasoning |
| **GPT-5 Realtime**       | Ultra-low-latency voice turns                 | **Speech-to-Speech** and **Dualplex**   |
| **GPT-4o**               | Strong reasoning and multimodal understanding | Complex tasks (higher latency)          |
| **Gemini Flash 2.0/2.5** | Ultra-fast native audio for voice turns       | **Speech-to-Speech** only               |

**Quick selection guide:**

* **Speed is critical:** Dualplex or Speech-to-Speech with GPT Realtime; Gemini only in Speech-to-Speech
* **Rich reasoning needed:** Use GPT-4o or GPT-5 Mini with filler audios to offset latency

### LLM Temperature

**Range:** 0.0 - 1.0 | **Default:** 0.1

Adjust the level of creativity of the AI when generating responses. Lower value yields better function call results.

<CardGroup>
  <Card title="Lower (0.0-0.3)" icon="snowflake">
    **More stable:** Predictable responses, better for function calling and business use cases
  </Card>

  <Card title="Higher (0.7-1.0)" icon="fire">
    **More random:** Creative and varied responses, good for casual conversations
  </Card>
</CardGroup>

<Note>
  **Special behavior:** For GPT-5 Mini and GPT-5 Nano models in Pipeline mode, temperature is automatically set to 1.0 for optimal performance.
</Note>

### Duration Settings

Control timing and call limits to optimize user experience and costs:

<AccordionGroup>
  <Accordion title="Re-engagement Interval" icon="clock">
    **Range:** 7 - 600 seconds | **Default:** 30 seconds

    AI will try to re-engage the user if no reply is detected within this time.

    **Recommended:** 30-60 seconds for professional calls.
  </Accordion>

  <Accordion title="Re-engagement Prompt" icon="message">
    Custom prompt used when the AI tries to re-engage the user after silence.

    **Default:** Uses a standard re-engagement phrase like "Are you still there?"

    **Customization:** Write a prompt that instructs the AI how to re-engage.

    **Examples:**

    * "Gently ask if they are still there and if they need more time."
    * "Politely check if they have any questions."

    <Warning>
      Variables like `{customer_name}` cannot be injected directly in this prompt. The AI has access to the conversation history and main system prompt, so it can reference information from there.
    </Warning>

    <Tip>
      Leave empty to use the default re-engagement behavior.
    </Tip>
  </Accordion>

  <Accordion title="Max Call Duration" icon="timer">
    **Range:** 20 - 1200 seconds | **Default:** 600 seconds (10 minutes)

    Call will automatically end if this value is reached.

    **Recommended:** 5-10 minutes for lead qualification to control costs.
  </Accordion>

  <Accordion title="Max Silence Duration" icon="volume-off">
    **Range:** 1 - 120 seconds | **Default:** 40 seconds

    Call will end if user doesn't reply within this time.

    **Recommended:** 30-45 seconds to balance patience with efficiency.
  </Accordion>

  <Accordion title="Ringing Time" icon="phone">
    **Range:** 1 - 60 seconds | **Default:** 30 seconds

    For how long the call will ring before marking as unanswered. **Good when you want to avoid voicemail by setting a lower value.**
  </Accordion>
</AccordionGroup>

<Tip>
  **Cost optimization:** Lower duration limits help control per-minute costs, especially important for high-volume campaigns.
</Tip>

### Call Protection Settings

<AccordionGroup>
  <Accordion title="Noise Cancellation" icon="shield">
    **Default:** Enabled

    Filters caller background noise for clearer speech recognition. Turn OFF if experiencing audio clipping.
  </Accordion>

  <Accordion title="End Call on Voicemail" icon="voicemail">
    **Default:** Enabled

    Immediately ends call if voicemail is detected during outbound calls (saves costs).
  </Accordion>

  <Accordion title="Voicemail Message" icon="voicemail">
    Prompt for the message the AI will say when voicemail is detected before ending the call.

    **Default:** Empty (hangs up immediately without leaving a message)

    **Use case:** Leave a brief message before hanging up so the recipient knows who called.

    **Example:** "Leave a brief voicemail message saying you called and ask them to call back."

    <Warning>
      Variables like `{company_name}` cannot be injected directly in this prompt. The AI has access to the conversation history and main system prompt, so it can reference information from there.
    </Warning>

    <Note>
      Only applies when "End Call on Voicemail" is enabled. Leave empty to hang up without a message.
    </Note>
  </Accordion>

  <Accordion title="Record Calls" icon="record-vinyl">
    **Default:** Enabled

    Records call audio for review and analysis. **Ensure compliance with local recording laws.**
  </Accordion>

  <Accordion title="Max Initial Silence" icon="timer">
    **Range:** 1 - 120 seconds | **Default:** 20 seconds (when enabled)

    If enabled, end the call if no first user response within this time. Counts only from call start to first user response.

    **Use case:** Detect if anyone actually answered the phone.
  </Accordion>
</AccordionGroup>

## Synthesizer Settings

Configure text-to-speech voice parameters for natural-sounding conversations.

**Available for:** Pipeline and Dualplex modes only. Speech-to-Speech mode uses native voice generation.

### Voice Tuning Parameters

Fine-tune your assistant's voice characteristics for optimal performance:

<AccordionGroup>
  <Accordion title="TTS Emotion" icon="face-smile">
    **Default:** Enabled

    When enabled, the AI will add emotional cues to the synthesized speech based on the context of the conversation. This makes the voice sound more natural and expressive.

    **Effects:**

    * Adjusts tone based on conversation context (happy, concerned, empathetic)
    * Adds natural inflections and emphasis
    * Makes the assistant sound more human-like

    <Note>
      Disable if you prefer a more neutral, consistent tone across all conversations.
    </Note>
  </Accordion>

  <Accordion title="Voice Stability" icon="wave-square">
    **Range:** 0.0 - 1.0 | **Default:** 0.7

    Lower settings make the voice more expressive but less predictable, while higher settings make it steadier but less emotional.

    <CardGroup>
      <Card title="More Expressive (0.0-0.3)" icon="sparkles">
        Dynamic and varied delivery but less predictable
      </Card>

      <Card title="More Stable (0.7-1.0)" icon="shield-check">
        Consistent and steady but less emotional range
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Voice Similarity" icon="fingerprint">
    **Range:** 0.0 - 1.0 | **Default:** 0.5

    Determines how closely the AI matches the original voice. Higher settings potentially include unwanted noise from the original recording.

    <CardGroup>
      <Card title="More Stable (0.0-0.4)" icon="filter">
        Cleaner audio but less accurate to original voice
      </Card>

      <Card title="More Similar (0.6-1.0)" icon="copy">
        Accurate to original but may include background noise
      </Card>
    </CardGroup>

    <Warning>
      **For cloned voices:** Start at 0.5 and increase gradually. Higher similarity can introduce unwanted artifacts from the original recording.
    </Warning>
  </Accordion>

  <Accordion title="Speech Speed" icon="gauge">
    **Range:** 0.7 - 1.2 | **Default:** 1.0

    Adjust the speed of the AI's speech for optimal comprehension and user experience.

    <CardGroup>
      <Card title="Slower (0.7-0.85)" icon="turtle">
        Better for complex information or older demographics
      </Card>

      <Card title="Normal (0.9-1.1)" icon="clock">
        Standard conversational pace for most use cases
      </Card>

      <Card title="Faster (1.15-1.2)" icon="rabbit">
        Quick conversations or time-sensitive scenarios
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

## Transcriber Settings

Configure speech-to-text recognition for optimal accuracy and speed.

**Available for:** Pipeline mode only. Speech-to-Speech and Dualplex modes use integrated transcription.

### Provider Selection

Choose the best transcriber for your language and use case. The provider that will be used to transcribe the user speech.

<CardGroup>
  <Card title="Azure" icon="cloud">
    **Accuracy:** ⭐⭐⭐⭐
    **Latency:** Slower

    Best for highest transcription fidelity when accuracy is critical.
  </Card>

  <Card title="Gladia" icon="bolt">
    **Accuracy:** ⭐⭐⭐
    **Latency:** Faster

    Good all-rounder for most languages. Supports multilingual configurations.
  </Card>

  <Card title="Deepgram" icon="waveform">
    **Accuracy:** ⭐⭐⭐
    **Latency:** Faster

    Solid choice for English and major languages.
  </Card>
</CardGroup>

<Note>
  Different languages, accents, or background noise can impact each provider differently. Test which performs better for your specific language and audio setup.
</Note>

### Endpoint Configuration

<CardGroup>
  <Card title="AI Turn Detection" icon="brain">
    Uses AI to intelligently detect when the caller has finished speaking
  </Card>

  <Card title="Voice Activity Detection (VAD)" icon="microphone">
    **Default:** Traditional voice activity detection

    Choose how the AI will detect the end of the user phrase
  </Card>
</CardGroup>

### Voice Activity Detection (VAD)

Control when your assistant starts and stops talking. See [Handling interruptions guide](/conversation-design/interruptions) for detailed VAD configuration.

<Warning>
  Fine-tune these settings if experiencing interruption issues or sluggish responses.
</Warning>

<AccordionGroup>
  <Accordion title="Endpoint Sensitivity" icon="microphone">
    **Range:** 0 - 5 seconds | **Default:** 0.5

    Adjust the time the AI will wait for the user to speak after the last word. Lower values make the AI faster, higher values are better for long user phrases.

    * **0 (Faster):** Quick responses but may cut off callers
    * **5 (Slower):** Waits longer, reduces interruptions
  </Accordion>

  <Accordion title="Interrupt Sensitivity" icon="volume-off">
    How easily the assistant stops when caller talks over it. Controls the sensitivity for detecting when a caller is trying to interrupt.
  </Accordion>

  <Accordion title="Minimum Interrupt Words" icon="list-ol">
    Require at least N caller words before interrupting assistant.
    **Use:** Prevents false triggers from background noise or brief sounds.
  </Accordion>

  <Accordion title="Turn Detection Threshold" icon="sliders">
    **Available for:** Speech-to-Speech and Dualplex modes only

    **Range:** 0 - 1 | **Default:** Auto (model decides)

    Controls how sensitive the multimodal model is to detecting when the caller has finished speaking. Lower values make the assistant respond faster, higher values wait longer for the caller to finish.

    * **Lower (0.3-0.5):** Faster responses, good for quick conversations
    * **Higher (0.7-0.9):** Waits longer, better for detailed responses
    * **Auto:** Let the model decide based on conversation context

    <Note>
      Only visible when using Speech-to-Speech or Dualplex modes.
    </Note>
  </Accordion>
</AccordionGroup>

<Tip>
  **Pro tip:** Start with default VAD settings and adjust based on real call testing. Increase endpoint sensitivity if callers get cut off, decrease if responses feel slow.
</Tip>


# Post-call Actions
Source: https://docs.autocalls.ai/ai-assistants/settings/post-call-actions

Extract data from the call and send it to an app/webhook for automation workflows.

Configure what happens after calls end - extract specific information from conversations and send it to external systems for further processing.

## Overview

Post-call actions automatically:

* Extract structured data from conversations using AI
* Send extracted variables to webhooks for automation
* Trigger workflows in connected platforms
* Update CRM records and databases
* Enable complex automation scenarios

## Post-call Variables

Define the variables that the AI will extract from the call and send to a webhook.

### Variable Configuration

Configure which information the AI should extract from each conversation:

<AccordionGroup>
  <Accordion title="Variable Definition" icon="code">
    Create variables that the AI will identify and extract from conversations.

    **How extraction works:**
    The AI analyzes the complete call transcript and considers your system prompt context to extract the requested variables. It understands what was discussed during the call and extracts relevant information based on your variable descriptions.

    **Configuration:**

    * **Name:** Variable identifier (3-16 characters, lowercase, alphanumeric)
    * **Type:** Data type for the extracted value
    * **Description:** Clear explanation so AI understands what to extract from the conversation

    **Variable Types:**

    * **String:** Text values (names, addresses, comments)
    * **Number:** Numeric values (quantities, prices, scores)
    * **True/False:** Boolean values (yes/no answers, objectives achieved)
  </Accordion>

  <Accordion title="Default Variables" icon="list">
    Every assistant includes these essential variables by default:

    **Status (True/False):** Whether the call objective was achieved or not

    **Summary (String):** Call summary in a few words

    You can add custom variables based on your specific use case.
  </Accordion>

  <Accordion title="Variable Examples" icon="lightbulb">
    Common variables for different scenarios:

    **Sales qualification:**

    * `budget` (Number): Customer's budget range
    * `decision_maker` (True/False): Is caller the decision maker
    * `timeline` (String): When they need the solution
    * `pain_points` (String): Main challenges mentioned

    **Appointment booking:**

    * `appointment_date` (String): Preferred appointment date
    * `service_type` (String): Type of service requested
    * `contact_method` (String): Preferred contact method

    **Support calls:**

    * `issue_type` (String): Category of the problem
    * `urgency_level` (Number): Priority score (1-10)
    * `resolution_status` (True/False): Was issue resolved
  </Accordion>
</AccordionGroup>

### Extraction Process

<AccordionGroup>
  <Accordion title="How AI Extracts Variables" icon="brain">
    The AI uses sophisticated analysis to extract variables from your calls:

    **Data sources:**

    * **Complete call transcript:** Everything said by both the AI and the customer
    * **System prompt context:** Your assistant's objectives and instructions help guide extraction
    * **Variable descriptions:** Clear descriptions you provide for each variable

    **Analysis method:**

    1. AI reviews the entire conversation transcript
    2. Considers the system prompt and call objectives
    3. Identifies relevant information based on variable descriptions
    4. Extracts and formats data according to specified types
    5. Validates extracted values before sending to webhook
  </Accordion>
</AccordionGroup>

### Best Practices

<Warning>
  **Variable naming:** Use lowercase, alphanumeric characters only. No spaces or special characters except underscores.
</Warning>

<Tip>
  **Clear descriptions:** Write descriptions that clearly explain what the AI should look for in the conversation transcript. The more specific and context-aware, the better the extraction accuracy.
</Tip>

<Note>
  **System prompt synergy:** Your variable descriptions work best when they align with your system prompt objectives. If your assistant is designed for lead qualification, your variables should reflect that purpose.
</Note>

## Webhook Configuration

Make a request to a URL that sends the extracted variables to external systems.

### Webhook Settings

<AccordionGroup>
  <Accordion title="Webhook Status" icon="check">
    **Enabled/Disabled:** Control whether webhooks are sent after calls

    **Default:** Disabled - Enable only when you have a webhook endpoint ready to receive data
  </Accordion>

  <Accordion title="Webhook URL" icon="link">
    **URL endpoint:** Where to send the extracted data

    **Format:** Must be a valid URL

    **Example:** `https://automate.autocalls.ai/api/v1/webhooks/your-webhook-id`

    **Test functionality:** Built-in test feature sends sample data to verify connectivity
  </Accordion>

  <Accordion title="Delivery Options" icon="gear">
    **Send webhook only on completed:**

    * **Yes (Default):** Only send data for completed calls
    * **No:** Send data for all calls regardless of completion status

    **Include recording in webhook:**

    * **Yes (Default):** Include recording URL in the webhook payload
    * **No:** Send only extracted variables without recording link
  </Accordion>
</AccordionGroup>

### Webhook Payload

The webhook will receive a comprehensive JSON payload containing call details, extracted variables, and transcript. For complete API documentation, see [Post-Call Webhook API](/api-reference/webhooks/post-call-webhook).

**Key payload fields:**

<AccordionGroup>
  <Accordion title="Call Information" icon="phone">
    * **id:** Unique call identifier
    * **type:** Channel and direction of the call — `inbound`, `outbound`, `web`, `whatsapp_inbound`, or `whatsapp_outbound`
    * **assistant\_id:** UUID of the assistant that handled the call
    * **assistant\_name:** Name of the assistant, as shown in the dashboard
    * **customer\_phone:** Customer's phone number (E.164 format)
    * **assistant\_phone:** Assistant's phone number
    * **duration:** Call duration in seconds
    * **status:** Call status (initiated, ringing, busy, in-progress, ended, completed, ended\_by\_customer, ended\_by\_assistant, unanswered, failed)
    * **created\_at/finished\_at:** ISO 8601 timestamps
  </Accordion>

  <Accordion title="Extracted Variables" icon="code">
    * **extracted\_variables:** AI-extracted data based on your post-call schema configuration (see [Post-call Variables](#post-call-variables) section above)
    * **input\_variables:** Variables passed before the call (see [Call Variables](/ai-assistants/settings/prompt-and-tools#call-variables))
    * Includes default variables (status, summary) plus your custom variables
  </Accordion>

  <Accordion title="Conversation Data" icon="message">
    * **transcript:** Detailed conversation transcript with timestamps
    * **formatted\_transcript:** Human-readable conversation format
    * **recording\_url:** Call recording URL (if enabled)
  </Accordion>

  <Accordion title="Campaign & Lead Data" icon="users">
    * **lead:** Lead information (for campaign calls)
    * **campaign:** Campaign details and settings
    * Only included for calls that are part of campaigns
  </Accordion>
</AccordionGroup>

**Example webhook payload:**

```json theme={null}
{
  "id": 12345,
  "type": "outbound",
  "assistant_id": "9c1f8e2a-4d3b-4a17-9f6e-2b5c8d0a7e31",
  "assistant_name": "Sales Agent",
  "customer_phone": "+1234567890",
  "assistant_phone": "+1987654321",
  "duration": 125,
  "status": "completed",
  "extracted_variables": {
    "status": true,
    "summary": "Customer interested in product demo",
    "lead_quality": "high",
    "budget": 5000
  },
  "input_variables": {
    "customer_name": "John Doe",
    "product_interest": "Pro Plan"
  },
  "transcript": [
    {
      "text": "Hello! This is Sarah from Autocalls.",
      "type": "transcript",
      "sender": "bot",
      "timestamp": 1756812511.315143
    },
    {
      "text": "Hi, I'm doing well, thanks.",
      "type": "transcript", 
      "sender": "human",
      "timestamp": 1756812514.104436
    }
  ],
  "formatted_transcript": "AI: Hello! This is Sarah from Autocalls.\\nCustomer: Hi, I'm doing well, thanks.",
  "recording_url": "https://app.autocalls.ai/storage/recordings/call-12345.mp4",
  "created_at": "2025-01-15T10:30:00.000000Z",
  "finished_at": "2025-01-15T10:32:05.000000Z"
}
```

### Testing Webhooks

<Tip>
  **Test before going live:** Use the "Make test request" button to send sample data to your webhook endpoint and verify it's working correctly.
</Tip>

**Test process:**

1. Configure your variables and webhook URL
2. Save your assistant settings
3. Click "Make test request"
4. Check your webhook endpoint receives the test data
5. Verify the payload structure matches your expectations

## Integration Examples

### Our Automation Platform

**Primary integration:** Use our built-in no-code automation platform for seamless workflows:

* **Direct webhook processing:** No external setup required
* **250+ app integrations:** Connect to CRM, email, calendars, and more
* **Visual workflow builder:** Create complex automation without code
* **Real-time data sync:** Instant processing of extracted variables
* **Pre-built templates:** Ready-to-use workflows for common scenarios

**Common automation workflows:**

* **CRM updates:** Automatically update contact records in HubSpot, Salesforce, Pipedrive
* **Email follow-ups:** Send personalized emails based on call outcomes
* **Lead scoring:** Update lead scores based on extracted variables
* **Calendar booking:** Schedule follow-up meetings automatically
* **Team notifications:** Alert team members about important calls

### External Platforms

**Any platform with webhook support:**

* Receive webhook data from our platform
* Process extracted variables in your own systems
* Create custom automation workflows
* Integrate with any API or service that accepts webhooks

**Use cases:**

* Connect to any CRM, email platform, or business tool
* Send data to custom applications
* Trigger workflows in third-party automation platforms
* Store data in external databases or systems

### Custom Development

**API endpoints:** Build custom receivers for webhook data

**Database integration:** Store call data in your own systems

**Business logic:** Trigger complex workflows based on extracted variables

## Testing Your Assistant

After configuring your assistant settings, it's important to test thoroughly before deploying to production.

### Testing Methods

<AccordionGroup>
  <Accordion title="Speak with Your Assistant" icon="microphone">
    **Web-based testing:** Use the "Speak with your assistant" button to test directly from your browser

    **Features:**

    * Real-time voice conversation through your web browser
    * Test all assistant capabilities including tools and knowledge base
    * No phone required - perfect for quick iterations
    * Immediate feedback on responses and behavior

    **Best for:** Quick testing during development and configuration
  </Accordion>

  <Accordion title="Phone Call Testing" icon="phone">
    **Real phone call testing:** Call your assistant from any phone number

    **Outbound assistants:**

    * If no specific number is set: Assistant calls from a random number
    * If caller ID is configured: Assistant calls from your specified number
    * Test the complete outbound flow including dialing and initial message

    **Inbound assistants:**

    * Call the assigned phone number directly
    * Test how the assistant handles incoming calls
    * Verify call routing and response quality

    **Best for:** Final testing with real phone conditions and audio quality
  </Accordion>
</AccordionGroup>

### Testing Checklist

<Tip>
  **Comprehensive testing:** Test all configured features including tools, knowledge base queries, variable extraction, and webhook delivery.
</Tip>

**Essential tests:**

* Voice clarity and response speed
* Knowledge base integration (if configured)
* Tool functionality (transfer, scheduling, etc.)
* Variable extraction accuracy
* Webhook delivery (check your endpoint receives data)
* Edge cases and error handling

## Web Widget Integration

Configure your assistant to work as a web widget on your website for seamless customer interactions.

### Widget Configuration

<AccordionGroup>
  <Accordion title="Widget Setup" icon="code">
    **Easy integration:** Add your AI assistant to any website with a simple code snippet

    **Features:**

    * **Voice chat:** Customers can speak directly to your assistant
    * **Text fallback:** Option for text-based conversations
    * **Customizable appearance:** Match your brand colors and styling
    * **Mobile responsive:** Works on all devices and screen sizes
  </Accordion>

  <Accordion title="Widget Behavior" icon="gear">
    **Smart interactions:** The widget adapts to your assistant configuration

    **Capabilities:**

    * Uses same knowledge base and tools as phone assistant
    * Supports all configured languages
    * Extracts same post-call variables
    * Sends webhooks for web conversations
    * Respects same system prompt and personality
  </Accordion>

  <Accordion title="Use Cases" icon="lightbulb">
    **Common applications:**

    **Customer support:** 24/7 automated support on your website
    **Lead qualification:** Qualify visitors before they contact sales
    **Appointment booking:** Allow visitors to schedule directly through the widget
    **FAQ handling:** Answer common questions instantly
    **Product demos:** Guide visitors through your product features
  </Accordion>
</AccordionGroup>

<Note>
  For detailed testing guides and widget integration instructions, see our [Testing Your Assistant](/ai-assistants/testing) documentation.
</Note>

<Note>
  For detailed webhook integration guides and examples, see our [Automation documentation](/automation/overview).
</Note>


# Prompt & Tools
Source: https://docs.autocalls.ai/ai-assistants/settings/prompt-and-tools

Configure your assistant's knowledge base, tools, variables, and system prompt to define its capabilities and behavior.

Configure the objective of the assistant and the tools it can use during calls.

## Knowledge Base

Give information to the assistant to use as a knowledge base when responding to customers. From website contents, documents, etc.

### Knowledge Base Selection

<AccordionGroup>
  <Accordion title="Choose Knowledge Base" icon="book-open">
    Select a knowledge base store containing relevant information for the assistant to use.

    **Requirements:**

    * Must be created in your [Knowledge Bases](/conversation-design/knowledge-bases) section first
    * Shows status (Active, Processing, etc.) and description
    * Only your own knowledge bases are available

    <Tip>
      Create knowledge bases from website content, PDFs, or custom documents to give your assistant domain-specific information. For comprehensive setup guide including content types, processing status, website scraping, and troubleshooting, see the complete [Knowledge Base Guide](/conversation-design/knowledge-bases).
    </Tip>
  </Accordion>

  <Accordion title="Knowledge Base Mode" icon="brain">
    Choose how the AI will use the knowledge base.

    <CardGroup>
      <Card title="Function Call" icon="function">
        **Recommended for most cases**

        Uses a function call to search for information in the knowledgebase, only when needed. More accurate and efficient.
      </Card>

      <Card title="Prompt Injection" icon="syringe">
        **For simple use cases**

        Performs a search after every customer speech. More accurate but can be slower without filler audios.
      </Card>
    </CardGroup>

    <Note>
      **Mode availability:** Speech-to-Speech and Dualplex modes only support Function Call mode.
    </Note>
  </Accordion>
</AccordionGroup>

## Custom Mid-Call Tools

Create and assign your own custom tools that AI can use **mid-call** with the customer.

<CardGroup>
  <Card title="Create Custom Tools" icon="plus">
    Build tools tailored to your specific business needs: API integrations, database queries, custom workflows, and external service calls.

    **Quick action:** Direct link to tool creation page.
  </Card>

  <Card title="Assign to Assistant" icon="link">
    Select which custom tools this assistant can use with multiple selection, search by name/description, and real-time assignment.

    **Scope:** Only your own tools are available.
  </Card>
</CardGroup>

<Tip>
  Read the [Custom Tools documentation](/ai-assistants/custom-tools) for detailed guides on creating and configuring custom tools.
</Tip>

## Default Tools

Choose built-in tools that AI can use **mid-call** with the customer.

<AccordionGroup>
  <Accordion title="Multi Call Transfer" icon="phone-arrow-right">
    Route calls to multiple destination phone numbers like different people or departments according to your flow.

    **Use cases:**

    * Escalation to human agents
    * Department routing
    * Specialist handoffs

    **Configuration options:**

    * **Standard mode:** Use regular phone numbers (e.g., +1234567890)
    * **Advanced mode:** Use SIP URI format for SIP providers (e.g., sip:+1234567890\@sip-server)

    **For SIP integrations:**

    * Set transfer to "Advanced" mode
    * Use SIP URI format: `sip:number@sip-server`
    * Verify your SIP provider supports SIP REFER
    * Test with different URI formats if transfers fail

    <Note>
      **Prompt instruction:** Include in your system prompt something like "call the transfer function when the user requests to speak with someone else" to ensure the AI uses this tool appropriately.
    </Note>

    <Tip>
      If transfers aren't working, see our [SIP Integration troubleshooting guide](/troubleshooting/sip-integration#transfer-phone-call-not-working) for detailed solutions.
    </Tip>
  </Accordion>

  <Accordion title="End Call" icon="phone-slash">
    Ends the call when the conversation is complete.

    **Use cases:**

    * Natural conversation conclusion
    * Objective achieved
    * Customer satisfaction confirmed

    <Note>
      **Prompt instruction:** If the AI doesn't call the end call function automatically, include in your system prompt "call the hang\_up function to close the call" when the conversation should end.
    </Note>
  </Accordion>

  <Accordion title="DTMF Input" icon="hashtag">
    Easily send keypad inputs during outbound calls, enabling smooth navigation through IVR menus and automated workflows. The AI navigates using keypad buttons when calling and responding to prompts.

    **Use cases:**

    * Navigate phone menus
    * Enter extension numbers
    * Input security codes
    * IVR system navigation

    <Note>
      **Prompt instruction:** Include in your system prompt instructions about when to use DTMF input, such as "use the send\_dtmf tool to navigate phone menus when needed to reach the right person."
    </Note>

    For detailed information about DTMF capabilities, see [Tools & Functions](/ai-assistants/tools-and-functions#4-dtmf-input).
  </Accordion>

  <Accordion title="Appointment Scheduling" icon="calendar">
    Real-time booking scheduling integration with multiple calendar platforms.

    **Available integrations:**

    * **Cal.com:** Full setup guide available at [Cal.com Scheduling](/ai-assistants/cal-com-scheduling)
    * **GoHighLevel:** Complete integration guide at [GoHighLevel Scheduling](/ai-assistants/gohighlevel-scheduling)
    * **Calendly:** Full setup guide available at [Calendly Scheduling](/ai-assistants/calendly-scheduling)

    **Use cases:**

    * Book appointments with calendars
    * Check real-time availability
    * Send automatic confirmation details
    * Sync with existing calendar systems

    **Setup:**

    1. Select your calendar provider (Cal.com, GoHighLevel, or Calendly)
    2. Authenticate with your calendar account
    3. Choose the event type/calendar to use for bookings
    4. The AI will automatically check availability and book appointments

    <Note>
      Available when calendar integration is enabled in your platform settings.
    </Note>
  </Accordion>
</AccordionGroup>

## Call Variables

Define variables that can be passed **before** making the call and used in the prompt **like&#x20;**.

### Variable Configuration

<AccordionGroup>
  <Accordion title="Variable Definition" icon="code">
    Create call variables to pass information to your assistant before the call starts.

    **Setup process:**

    * Define variable names and default values
    * Pass values when creating calls/leads or importing clients
    * Variables available immediately in prompts and during calls
    * Use for personalization and context

    **Configuration:**

    * **Variable name:** The identifier (e.g., `customer_name`)
    * **Default value:** Used when not passed (e.g., "John")
  </Accordion>

  <Accordion title="Variable Usage" icon="code">
    How to use call variables in your assistant:

    **In system prompts:**

    * Reference variables with `{variable_name}` syntax
    * Personalize conversations dynamically
    * Provide context-specific information

    **Examples:**

    * `{customer_name}` for personalization ("Hello ")
    * `{email}` for calendar integrations
    * `{account_type}` for tailored responses
    * `{company}` for business context
  </Accordion>

  <Accordion title="Data Sources" icon="database">
    Ways to populate call variables:

    **Manual entry:**

    * When creating individual calls
    * Through campaign lead creation

    **Import methods:**

    * CSV import with variable columns
    * API integration with client data
    * Direct CRM synchronization

    **Automation platform integrations:**

    * **GoHighLevel (GHL):** Automatically pull contact data and custom fields
    * **Google Sheets:** Import leads with variables from spreadsheet columns
    * **Connect with 250+ popular tools** and platforms using our no-code platform
    * **Any other platform** through webhooks for custom integrations

    **Platform integration:**

    * Automatically populated from client profiles
    * Connected to existing customer databases
    * No-code automation workflows
  </Accordion>
</AccordionGroup>

<Note>
  Call variables are essential for personalizing AI conversations. They allow the AI to use specific customer information during calls, making interactions more relevant and effective.
</Note>

## Call Flow Configuration

### Who Speaks First?

Control whether your assistant or the customer initiates the conversation.

<CardGroup>
  <Card title="AI Assistant" icon="robot">
    **Default behavior:** Assistant starts the conversation

    The AI will immediately greet the caller and begin the conversation flow as soon as the call connects.

    **Best for:** Most outbound scenarios, sales calls, appointment reminders
  </Card>

  <Card title="Customer" icon="user">
    **Wait for customer:** Assistant listens first

    If you choose "Customer", the AI will wait for the customer to speak first before responding.

    **Best for:** Inbound support calls, reception scenarios, reactive assistance
  </Card>
</CardGroup>

### Initial Message

Configure the first thing your assistant says when the call begins.

<AccordionGroup>
  <Accordion title="Initial Message Text" icon="message">
    Write the opening message your assistant will speak at the start of each call.

    **Best practices:**

    * Keep it concise and friendly
    * Introduce your company/purpose clearly
    * Set expectations for the conversation
    * Use variables for personalization (e.g., `{customer_name}`)

    **Example:** "Hi , this is Sarah from ABC Company. I'm calling to follow up on your recent inquiry about our services. Do you have a moment to chat?"
  </Accordion>

  <Accordion title="Initial Audio File" icon="volume">
    **Optional:** Upload a custom audio file instead of text-to-speech

    **Requirements:**

    * MP3 or WAV format
    * Clear, high-quality recording
    * Professional voice and tone
    * Matches your assistant's voice if using voice cloning

    **Benefits:**

    * Perfect pronunciation and delivery
    * Consistent brand voice
    * Professional first impression
    * No text-to-speech latency for opening

    <Tip>
      This works best if the AI voice is cloned using the same voice used in the initial audio.
    </Tip>
  </Accordion>
</AccordionGroup>

<Note>
  See our [Initial Message guide](/ai-assistants/initial-message) for detailed best practices and examples.
</Note>

## System Prompt

Define the assistant's personality, objectives, and behavior guidelines.

### Editing Tools

Choose the editing experience that works best for you:

<CardGroup>
  <Card title="AI Prompt Editor" icon="sparkles" href="/ai-assistants/ai-prompt-editor">
    **Chat-based editing with AI assistance**

    Describe changes in plain language and let AI suggest intelligent modifications. Review and accept/reject each change individually.

    **Best for:** Quick iterations, improving existing prompts, text-focused editing
  </Card>

  <Card title="Flow Builder" icon="share-nodes" href="/ai-assistants/flow-builder">
    **Visual drag-and-drop editor**

    Design conversation flows by connecting nodes on a canvas. Create branching logic and multi-path decision trees visually.

    **Best for:** Complex call flows, structured scripts, visual thinkers
  </Card>
</CardGroup>

<Note>
  Both tools store the prompt in the same field - switching between them is possible but may require adjustments.
</Note>

### Prompt Configuration

<CardGroup>
  <Card title="Custom Prompt" icon="pencil">
    Write your own system prompt from scratch

    * Full control over assistant behavior
    * Tailored to specific use cases
    * Markdown formatting supported
  </Card>

  <Card title="Template Library" icon="folder">
    Start with pre-built templates

    * Multiple languages available
    * Different conversation types
    * Proven effective prompts
  </Card>
</CardGroup>

### Best Practices

<AccordionGroup>
  <Accordion title="Be Specific" icon="bullseye">
    Clearly define the assistant's role, objectives, and constraints.

    **Include:**

    * Who the assistant represents
    * What they're trying to achieve
    * What they should/shouldn't do
  </Accordion>

  <Accordion title="Set Boundaries" icon="shield">
    Define what topics and actions are off-limits.

    **Consider:**

    * Data privacy requirements
    * Legal compliance
    * Brand guidelines
  </Accordion>

  <Accordion title="Use Examples" icon="lightbulb">
    Provide sample conversations to guide behavior.

    **Examples help with:**

    * Tone and style
    * Response length
    * Handling objections
  </Accordion>
</AccordionGroup>

<Tip>
  See our [System Prompt guide](/ai-assistants/system-prompt) for detailed best practices and examples.
</Tip>


# System Prompts
Source: https://docs.autocalls.ai/ai-assistants/system-prompt

Learn how to create effective system prompts - the core intelligence of your AI assistant

The system prompt is the most crucial component of your AI assistant. It defines your assistant's personality, behavior, knowledge, and capabilities. Think of it as the "brain" and "training manual" combined.

## Editing Options

You have three ways to create and edit your system prompt:

<Frame>
  <img alt="System Prompt Editing Options" />
</Frame>

<CardGroup>
  <Card title="AI Prompt Editor" icon="sparkles" href="/ai-assistants/ai-prompt-editor">
    Chat with AI to edit your prompt. Best for quick iterations and improvements.
  </Card>

  <Card title="Flow Builder" icon="share-nodes" href="/ai-assistants/flow-builder">
    Visual drag-and-drop editor. Best for structured, multi-path conversations.
  </Card>

  <Card title="Classic Editor" icon="pencil">
    Direct text editing. Best for full control and manual fine-tuning.
  </Card>
</CardGroup>

## Quick Start with Templates

To get started quickly:

1. Go to your [assistant settings](/ai-assistants/settings/prompt-and-tools#system-prompt)
2. Find the system prompt field
3. Click the "Templates" button nearby
4. Choose a template that matches your use case
5. Customize it for your needs

## Language Support

Your system prompt can be written in any language, regardless of the spoken language setting:

* Write the prompt in your preferred language
* Set the spoken language separately in [assistant settings](/ai-assistants/settings/general#language-configuration)
* The AI will follow the prompt's instructions while speaking in the selected language

For example:

* System prompt in English, spoken language set to Spanish
* System prompt in German, spoken language set to French
* System prompt in Chinese, spoken language set to English

## Why They Matter

Your system prompt:

* Shapes how the AI thinks and responds
* Defines conversation boundaries
* Provides essential knowledge
* Controls behavior and tone
* Determines handling of edge cases

## Key Components

A good system prompt should include:

### 1. Role & Identity

```
You are a professional sales representative for [Company]. You specialize in [Product/Service] and have extensive knowledge of our offerings.
```

### 2. Conversation Style

```
Maintain a friendly, professional tone. Use clear, concise language. Avoid technical jargon unless specifically asked.
```

### 3. Key Information

```
Our main products are:
- Product A ($X/month): [features]
- Product B ($Y/month): [features]
Current promotion: 20% off first 3 months
```

### 4. Behavioral Guidelines

```
- Always verify customer information before discussing account details
- Transfer to a human agent if the customer seems frustrated
- Don't make promises about delivery dates
```

### 5. Response Framework

```
When asked about pricing:
1. First understand their needs
2. Present relevant package options
3. Explain the value proposition
4. Share any applicable discounts
```

## Best Practices

1. **Be Specific**

   * Clear instructions get better results
   * Include examples of good responses
   * Define what NOT to do

2. **Structure Matters**

   * Organize information logically
   * Use bullet points and sections
   * Keep related information together

3. **Test and Iterate**
   * Start with a basic prompt
   * Test various scenarios
   * Refine based on call recordings
   * Add handling for edge cases

## Common Mistakes

* **Too Vague**: "Be helpful and professional" (Not specific enough)
* **Too Rigid**: Scripting every possible response (Reduces natural flow)
* **Information Overload**: Including unnecessary details
* **Missing Guidelines**: Not specifying how to handle common situations

## Example Structure

```
# Role and Purpose
[Define who the AI is and its main goals]

# Core Knowledge
[Essential information about products/services]

# Conversation Guidelines
[How to interact with customers]

# Response Patterns
[How to handle specific situations]

# Limitations and Boundaries
[What the AI should NOT do]
```

## Testing Your Prompt

1. Make test calls covering:

   * Common scenarios
   * Edge cases
   * Difficult situations
   * Various customer personalities

2. Review and adjust:
   * Listen to call recordings
   * Check response accuracy
   * Verify tone consistency
   * Test knowledge retention

## Optimization Tips

* Start with Fast Engine for quick iterations
* Use call recordings to identify gaps
* Add examples of good/bad responses
* Include handling for unexpected questions

***

**Pro Tip:** Your system prompt is a living document - regularly update it based on actual call experiences and customer interactions.


# Test Chat Interface
Source: https://docs.autocalls.ai/ai-assistants/test-chat

Test your assistant with a text-based chat interface for rapid iteration

The Test Chat interface provides a quick way to test your assistant's conversation flow without making actual phone calls.

## Accessing Test Chat

1. Navigate to your assistant's page
2. Click the **"Test Assistant"** button with the chat icon
3. A chat interface will open in a slide-over panel

<Frame>
  <img alt="Test Assistant Button" />
</Frame>

## How It Works

The Test Chat interface simulates a conversation with your assistant:

* **Text-based interaction:** Type messages instead of speaking
* **Real AI responses:** Your assistant processes messages using the same logic as phone calls
* **Variable testing:** Test how your assistant handles variables and data collection
* **Tool execution:** See how your assistant uses configured tools and functions
* **Fast iteration:** Quickly test prompt changes without phone calls

## When to Use Test Chat

**Ideal for:**

* Testing conversation flow and logic
* Verifying prompt behavior and responses
* Debugging variable collection
* Testing tool/function calls
* Rapid prompt iteration

**Not suitable for:**

* Testing voice quality or speech recognition
* Testing call transfers (use phone testing)
* Testing phone-specific features
* Evaluating conversation timing and pacing

## Testing Workflow

**1. Test conversation flow with chat interface:**

* Verify your assistant understands user intents
* Check that variables are collected correctly
* Ensure tools execute as expected
* Validate response quality

**2. Test voice quality with Web Call:**

* Verify voice clarity and tone
* Check response timing and pacing
* Test interruption handling

**3. Final testing with Phone Call:**

* Test all features including call transfers
* Verify real-world call quality
* Test edge cases and error handling

<Note>
  Test Chat creates conversation records that appear in your **Conversations** page, helping you review and analyze test sessions.
</Note>

## Cost Considerations

Test Chat interactions:

* Use AI processing credits from your account balance
* Are typically more cost-effective than phone testing
* Allow for faster iteration with immediate feedback
* Create conversation records for later review

<Tip>
  Use Test Chat for initial prompt development, then move to phone testing for final validation before deploying to production.
</Tip>


# Testing Your Assistant
Source: https://docs.autocalls.ai/ai-assistants/testing

Learn how to quickly test your AI assistant for both inbound and outbound calls

There are multiple ways to test your AI assistant, depending on whether you want to test inbound or outbound functionality and your preferred testing method.

## Web Call Testing

**Browser-based voice testing** with the "Speak with your assistant" button:

1. Go to your assistant dashboard
2. Click "Speak with your assistant" button
3. Test voice conversation directly in your browser
4. Evaluate voice quality, response timing, and conversation flow

**Pros:**

* Instant voice testing without phone setup
* Tests voice components and timing
* Easy access from dashboard

**Cons:**

* Call transfer functionality will not work during web testing

<Warning>
  **Cost Notice:** Web call testing deducts 1 minute from your account balance per minute of call for AI processing costs. This is not free testing.
</Warning>

## Phone Call Testing

**Real phone call testing** for outbound capabilities:

1. Go to your assistant's settings
2. Find the "Speak to your assistant" purple button
3. Enter your phone number
4. Click to initiate the test
5. You'll receive a call from your AI assistant immediately

## Testing Inbound Calls

**Real phone call testing** for inbound functionality:

1. Make sure you have a phone number assigned to your assistant
2. Call that number from any phone
3. Your AI assistant will answer and handle the call

## Testing Best Practices

**Start with web calls** for quick iteration:

* Test basic conversation flow and voice quality
* Verify prompt behavior and response timing
* Note: Call transfers won't work in web testing

**Move to phone calls** for comprehensive testing:

* Test all tools including call transfers
* Verify real-world call quality and timing
* Test edge cases and interruption handling

**Cost Management:**

* Both web and phone testing use account balance
* Plan your testing sessions to manage costs
* Use text-based prompt testing first when possible

***

**Tip:** Save your AI's phone number in your contacts to easily make inbound test calls whenever needed.


# Tools & Functions
Source: https://docs.autocalls.ai/ai-assistants/tools-and-functions

Explore the built-in tools and functions that enhance your AI assistant's capabilities during calls

Autocalls.ai offers built-in "tools" that your AI assistant can use during a call. These help you shape the conversation flow and automate actions like transferring calls or scheduling appointments.

## 1. End Call Tool

* **Purpose**: Tells the AI to politely wrap up the conversation.
* **How It Works**: You can specify in the system prompt or logic, for instance: "If the user says `goodbye`, end the call."
* **Configuration**: Enable in [Prompt & Tools settings](/ai-assistants/settings/prompt-and-tools#default-tools) and define conditions in your system prompt that should trigger the end call.

## 2. Transfer Tool

* **Purpose**: Moves the caller from the AI assistant to a human agent or external phone number.
* **Use Cases**: Warm leads on a sales call, escalations on a support call, etc.
* **Configuration**: Set up in [Prompt & Tools settings](/ai-assistants/settings/prompt-and-tools#default-tools) by adding the phone number or department the call should go to, and optionally a short hold message.

## 3. Appointment Scheduler

* **Purpose**: Lets the AI check your calendar availability and book appointments automatically.
* **Available Integrations**: Cal.com, GoHighLevel, and Calendly calendar systems
* **Typical Flow**:
  1. AI offers scheduling.
  2. Caller selects date/time.
  3. AI confirms and sends a confirmation (using email or SMS if configured).
* **Configuration**: Set up in [Prompt & Tools settings](/ai-assistants/settings/prompt-and-tools#default-tools) with your calendar integration.

## 4. DTMF Input

* **Purpose**: Allows the AI to send keypad inputs during calls to navigate phone menus, IVR systems, and automated workflows.
* **How It Works**: The AI can press phone keypad buttons (0-9, \*, #) when encountering automated systems or menu prompts.
* **Use Cases**:
  * Navigate through company phone menus
  * Enter extension numbers to reach specific departments
  * Input security codes or account numbers
  * Bypass IVR systems to reach human agents
* **Configuration**: Enable in [Prompt & Tools settings](/ai-assistants/settings/prompt-and-tools#default-tools) and include instructions in your system prompt about when to use DTMF.

## 5. No-Code Automation Platform

* **Purpose**: After calls, the AI can trigger actions in the automation platform (like updating a CRM, sending an email, or logging results in Google Sheets).
* **Configuration**: Set up triggers and actions in the [Automation Platform](/automation-platform/introduction), then link to your assistant via webhook configuration in [Post-call Actions](/ai-assistants/settings/post-call-actions#webhook-configuration).

## 6. Custom Mid-Call Tools

* **Purpose**: Create your own custom API integrations that the AI can use during calls.
* **Use Cases**: Check inventory, verify customer data, fetch real-time information, or integrate with your own systems.
* **Types**: A **HTTP request** tool calls your own endpoint directly, or an **Automation Platform** tool auto-creates a linked no-code flow for multi-step logic.
* **Configuration**: Set up in [Prompt & Tools settings](/ai-assistants/settings/prompt-and-tools#custom-mid-call-tools) by defining API endpoints, parameters, static fields, and when the AI should use them. Values support dynamic [system variables](/ai-assistants/custom-tools#system-variables--dynamic-values) like `{{customer_phone}}`.
* For detailed setup instructions and examples, see our [Custom Mid-Call Tools Guide](/ai-assistants/custom-tools).

## 7. MCP Servers

* **Purpose**: Connect a remote [Model Context Protocol](https://modelcontextprotocol.io) server so the AI can use **many** external tools at once, discovered automatically.
* **Use Cases**: Connect a platform like HubSpot, your internal APIs, or knowledge tools to pull live data and trigger actions mid-conversation.
* **Configuration**: Add a server under the **Mid call tools / MCP** page, then assign it to an assistant. See the [MCP Servers Guide](/ai-assistants/mcp-servers).

***

**Note:** Tools can be combined. For instance, the AI can use a custom tool to check availability, then schedule an appointment, and finally transfer to a human agent if needed.


# Voice Selection & Voice Cloning
Source: https://docs.autocalls.ai/ai-assistants/voice-selection

Learn how to select built-in voices or clone your own voice for your AI assistants

Your AI assistant can speak with **built-in voices** or a **custom cloned voice**. Natural, realistic voices increase customer trust and engagement.

## TTS Provider

Select your Text-to-Speech provider in the assistant settings. Available in **Pipeline** and **Dualplex** modes.

**Available Providers:**

* **ElevenLabs** - High-quality voices
* **Cartesia** - Fast, low-latency synthesis

The TTS Provider dropdown appears after selecting a language.

## Voice Library

Each TTS provider has its own voice library. Select male/female, accent, or language based on your provider.

## Importing Voices from the Provider Library

Beyond the built-in catalog, you can import any public voice from your TTS provider's own library (ElevenLabs Voice Library or Cartesia Library). Available in **Pipeline** and **Dualplex** modes.

**Steps:**

1. Click "Import voice" next to the voice selector
2. Pick the provider (ElevenLabs or Cartesia)
3. Open the provider's voice library and find a voice you like
4. Copy the voice link or ID (the ⋮ menu next to the voice)
5. Paste it in the import field and click Import

<Frame>
  <img alt="Copy voice link in the ElevenLabs Voice Library" />
</Frame>

<Frame>
  <img alt="Copy ID in the Cartesia Voice Library" />
</Frame>

You'll get a notification when the voice is ready — it then appears in the voice picker like any other voice, billed at the same flat per-minute rate.

**Notes:**

* ElevenLabs voices with a custom price set by their creator cannot be imported.
* Private or unshared voices cannot be imported — only public library voices.

## Voice Cloning

Clone a voice from an audio sample. Available in **Pipeline** and **Dualplex** modes.

**Clone to Provider:**

* **Cartesia** - Single audio file, at least 10 seconds, 1 speaker, no background noise
* **ElevenLabs** - Samples over 1 minute, 1 speaker, no background noise. Max 5 minutes total. Quality over quantity.

**Steps:**

1. Click "Clone voice" next to voice selector
2. Select provider (Cartesia or ElevenLabs)
3. Choose the voice language
4. Enter a name for your voice
5. Record or upload audio
6. Wait for processing
7. Select your new voice from dropdown

## Best Practices

1. **High-Quality Audio**: Clearer samples give better results
2. **Steady Delivery**: Natural tone, no abrupt changes
3. **No Background Noise**: Record in a quiet environment
4. **Legal**: Ensure permission to clone voices that aren't yours

***

**Tip:** After selecting or cloning a voice, do a test call to confirm it sounds as expected.


# Web Widget
Source: https://docs.autocalls.ai/ai-assistants/web-widget

Embed your AI assistant on your website with voice and chat capabilities

Add your AI assistant to any website with a customizable widget that supports voice calls, text chat, or both.

## Overview

The Web Widget allows website visitors to interact with your AI assistant directly through:

* **Voice conversations:** Real-time voice calls in the browser
* **Text chat:** Messaging interface for text-based interactions
* **Hybrid mode:** Seamless switching between voice and chat

## Accessing Widget Configuration

1. Navigate to your assistant's edit page
2. Click the **"Web widget"** button (yellow/warning color)
3. The widget configuration panel opens with live preview

<Frame>
  <img alt="Web Widget Button Location" />
</Frame>

<Note>
  Web Widget is a premium feature. Ensure your plan includes web widget access before configuration.
</Note>

## Widget Modes

Choose how visitors interact with your assistant:

### Voice & Chat (Recommended)

Users can seamlessly switch between voice and text during conversations.

**Best for:**

* Maximum flexibility for users
* Accessibility (voice for mobile, chat for quiet environments)
* Complex interactions requiring both modes

### Chat Only

Text-based messaging interface only.

**Best for:**

* Customer support and FAQs
* Environments where voice isn't appropriate
* Lead capture and qualification forms

### Voice Only

Real-time voice conversations only.

**Best for:**

* Phone-like experience on website
* Voice-first use cases
* Hands-free interactions

## Configuration Options

### General Tab

<Frame>
  <img alt="Widget General Tab" />
</Frame>

**Widget Mode:** Voice, Chat, or Voice & Chat

**Widget Size:** Choose between standard or **extra large** layout

* **Standard**: Compact floating widget suitable for most use cases
* **Extra Large**: Half-screen panel on desktop, full-screen on mobile — ideal for detailed conversations

**Position:** Choose from 8 positions (bottom-right, bottom-left, bottom-center, middle-right, middle-left, top-right, top-left, top-center)

**Primary Color:** Brand color for buttons and accents

**Toggle Button Size:** Small or Normal

**Toggle Button Style:** Animated (glass morphism) or Simple (flat design)

**Auto-Open on Page Load:** When enabled, the widget automatically expands when the page loads — no click required from the visitor.

### Button Tab

<Frame>
  <img alt="Widget Button Tab" />
</Frame>

**Custom Avatar:** Upload your own avatar image to replace the default widget icon. Appears on the toggle button and in the chat header. Max file size: 512KB, 1:1 aspect ratio (square).

**Button Main Text** (default: "Need help?") — primary text on the widget button

**Button Sub Text** (default: "Chat with us") — secondary text, hidden when using the small button size

**Tab Labels (Voice & Chat mode only):**

* Voice Tab Label (default: "Voice") — rename to match your brand language (e.g., "Call Us", "Speak")
* Chat Tab Label (default: "Chat") — rename to match your brand language (e.g., "Message", "Text")

### Header & Modal Tab

<Frame>
  <img alt="Widget Header & Modal Tab" />
</Frame>

**Header Title** (default: "AI Assistant")

**Header Subtitle** (default: "Ready to help you ✨")

**Modal Title** (default: "Ready to chat?")

**Start Button Text** (default: "Start Voice Chat")

**Modal Description** (default: "Click below to start your conversation")

### Chat Settings Tab

<Frame>
  <img alt="Widget Chat Settings Tab" />
</Frame>

<Note>
  This tab is only visible when the widget mode includes chat (Chat Only or Voice & Chat).
</Note>

**Chat Placeholder** (default: "Type your message...")

**Send Button Label** (default: "Send message") — accessibility label for the send button

**Show Function Calls:** When disabled (default), LLM tool calls (e.g., calendar lookups, knowledge base queries) are hidden from the chat, keeping the conversation clean for end users. Enable to show tool usage details.

### Clickable Links in Chat

The chat widget supports **markdown formatting**, so your AI assistant can send clickable links, bold text, lists, and more.

To include clickable URLs in chat messages, use markdown link format in your assistant's prompt or initial message:

```
Check out our [latest offers](https://example.com/offers) or visit our [help center](https://example.com/help).
```

<Tip>
  Add an instruction to your assistant's prompt like: *"When sharing links or URLs, always format them as clickable markdown links: `[link text](url)`"* — this ensures the AI consistently outputs clickable links instead of plain text URLs.
</Tip>

### Voice Settings Tab

<Frame>
  <img alt="Widget Voice Settings Tab" />
</Frame>

<Note>
  This tab is only visible when the widget mode includes voice (Voice Only or Voice & Chat).
</Note>

**Connecting Text** (default: "Connecting...")

**Disconnect Text** (default: "Disconnect")

**Error Text** (default: "Connection failed. Please try again.")

### Pre-Chat Form

<Frame>
  <img alt="Pre-Chat Form Configuration" />
</Frame>

Collect information before starting conversations:

**Form Configuration:**

* Pre-form Title (default: "Before we start...")
* Pre-form Description (default: "Please provide some information to help us assist you better")
* Submit Button Text (default: "Continue")

**Form Fields:**
Add custom fields to collect data:

* **Variable Name:** Internal variable name (maps to assistant variables). Only letters, numbers, dashes, and underscores allowed.
* **Field Label:** Display label shown to users
* **Field Type:** Text, Email, Phone, or Textarea
* **Required:** Make field mandatory
* **Placeholder:** Placeholder text shown in the field
* **Helper Text:** Optional description below the field

**Variable Mapping:**
Form field names automatically map to your assistant's variables, making collected data available during conversations.

**Example Form Fields:**

```
Name: Full Name (required, text)
Email: Email Address (required, email)
Company: Company Name (optional, text)
Message: How can we help? (optional, textarea)
```

### AI Response Settings

<Frame>
  <img alt="Widget AI Response Settings" />
</Frame>

**AI Enabled:** When toggled on (default), the AI assistant automatically responds to incoming messages. Turn this off if you want to use the widget for manual-only conversations — messages are collected but the AI does not reply.

### Conversation Webhook

<Frame>
  <img alt="Widget Conversation Webhook" />
</Frame>

**Webhook URL:** Enter a URL to receive a webhook notification whenever a new conversation starts via the widget. Use this to trigger automation flows, log events to your CRM, or notify your team in real-time.

### Widget Display

<Frame>
  <img alt="Widget Display Toggle" />
</Frame>

**Enable Widget:** Master toggle that controls whether the widget loads on your website. When disabled, the widget will not appear even if the embed script is installed on your site. Use this to temporarily hide the widget without removing code from your website.

## Live Widget Preview

<Frame>
  <img alt="Widget Live Preview" />
</Frame>

At the top of the configuration panel, a live preview shows exactly how your widget will look and behave on a website. The preview updates in real-time as you change any setting.

**Copy Preview URL** — copies the preview URL to your clipboard so you can open it in a separate browser tab or share it with your team for review.

**Reset Data** — clears all stored conversation history, form submissions, and preferences in the preview. Use this to simulate a first-time visitor experience after testing.

<Tip>
  The preview is fully interactive — you can click the widget button, fill out the pre-chat form, and start a real conversation to test your configuration before deploying.
</Tip>

### Embed Code

<Frame>
  <img alt="Widget Embed Code" />
</Frame>

The embed code section provides a ready-to-copy script tag. Click **Copy** to copy it to your clipboard, then paste it into your website before the closing `</body>` tag:

```html theme={null}
<script src="https://app.autocalls.ai/embed.js"
        data-assistant-id="your-assistant-id">
</script>
```

<Warning>
  Save your widget settings **before** copying the embed code. The script loads all configuration from the server, so any unsaved changes won't appear on your website.
</Warning>

## Identifying logged-in users

When the widget is embedded in an authenticated dashboard, pass the visitor's identity from your backend so they do not have to fill in the pre-chat form.

```html theme={null}
<script
  src="https://app.autocalls.ai/embed.js"
  data-assistant-id="your-assistant-id"
  data-customer-identifier="${session.universal_customer_id}"
  data-variables='{"customer_name":"John Smith","customer_email":"john@acme.com","company":"Acme Corp"}'
></script>
```

| Attribute                  | Purpose                                                                                                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-variables`           | JSON object of conversation variables. Keys matching assistant variables (for example `{customer_name}`) are substituted in the prompt and opening message. |
| `data-customer-identifier` | Stable user ID stored on the conversation so you can find it in [Conversations](/conversations/overview).                                                   |
| `data-ucid`                | Alias for `data-customer-identifier`.                                                                                                                       |

**Skip the pre-chat form:** if every required form field already has a non-empty value in `data-variables` (or previously saved form data), the form is not shown. Extra keys still reach the assistant.

**Find the user in the app:** the identifier is stored as the conversation's customer identifier (`external_identifier`). The first conversation for that assistant + identifier keeps the lookup slot. Later conversations still include `customer_identifier` in their variables.

### Reset identity on logout

Call this when the user logs out of your site, and stop injecting `data-variables` / `data-customer-identifier` on the next page:

```js theme={null}
window.AIChatWidget.reset('your-assistant-id');
```

Equivalent postMessage:

```js theme={null}
iframe.contentWindow.postMessage({
  type: 'widget-clear-storage',
  assistantId: 'your-assistant-id'
}, '*');
```

This clears the stored conversation ID and form data, then reloads the widget.

## Installation

1. Configure and save your widget settings
2. Copy the embed code from the **Embed Code** section
3. Paste the script tag before the closing `</body>` tag on your website
4. Visit your website and verify the widget appears in the configured position
5. Test voice/chat functionality and pre-chat form (if configured)

## Widget Behavior

### First Visit

* Widget button appears in configured position
* Click opens modal/chat interface
* Pre-chat form displays (if configured)
* After form submission, conversation starts

### Return Visits

* Chat history is restored from the previous conversation in this browser
* Form data is remembered (until the visitor clears site data or you call `AIChatWidget.reset`)
* Voice sessions do not resume — each voice connect starts a new call

### Conversation Tracking

All widget conversations appear in your [Conversations](/conversations/overview) page for review and analysis.

<Warning>
  HTTPS (SSL certificate) is required for voice functionality. HTTP sites can only use chat mode due to browser security restrictions.
</Warning>

## Troubleshooting

For setup and configuration issues, see [Web Widget Troubleshooting](/troubleshooting/web-widget).

## Next Steps

* Test widget using the live preview
* Embed code on your website
* Monitor conversations in the [Conversations](/conversations/overview) page


# What is an AI Assistant?
Source: https://docs.autocalls.ai/ai-assistants/what-is-ai-assistant

Understand what an AI Assistant is, its key components, and how it can help automate your phone interactions

An **AI Assistant** (sometimes called an agent) is your configurable bot that speaks with customers or leads over the phone—either when they call you (**inbound**) or when your system calls them (**outbound**).

## Why Use an AI Assistant?

* **Automate Common Interactions**: Answer FAQs, book appointments, or qualify leads 24/7.
* **Reduce Workload**: Free your human team from repetitive tasks like verifying contact info or taking messages.
* **Scalable**: One assistant can handle many calls in parallel, allowing you to grow without adding more agents.

## Key Components

1. **System Prompt**: The core instructions guiding how your assistant behaves.
2. **Initial Message**: The very first phrase the AI says (especially critical for inbound calls).
3. **Voice Settings**: Choose a built-in voice or clone your own.
4. **Tools** (Optional): Transfer, end call, scheduling, and more.

***

**Next Steps**

* Learn how to [Create and Edit an AI Assistant](/ai-assistants/settings/general).
* Explore the various [Tools & Functions](/ai-assistants/tools-and-functions) you can add to your assistant.


# Generate AI Reply
Source: https://docs.autocalls.ai/api-reference/ai/generate-reply

POST /user/ai/generate-reply
Generate an AI response using an assistant, identified by an external customer identifier

This endpoint generates an AI response for a given message using your configured assistant. It automatically creates or reuses conversations based on the customer identifier, making it ideal for integrating AI responses into external platforms, CRMs, or custom chat interfaces.

<Info>
  **Rate Limited** — This endpoint is rate limited to 5 requests per minute per API token to prevent abuse.
</Info>

### Request Body

<ParamField type="integer">
  The ID of the assistant to use for generating the response. Must belong to your account.
</ParamField>

<ParamField type="string">
  A unique identifier for the customer. This is used to maintain conversation context across multiple messages.

  Examples: phone number, email address, CRM contact ID, Facebook user ID.

  Maximum length: 255 characters.
</ParamField>

<ParamField type="string">
  The customer's message to respond to.
</ParamField>

<ParamField type="object">
  Optional context variables to pass to the assistant. These are merged with any existing conversation variables.

  Useful for passing customer data, session context, or other metadata.
</ParamField>

### Response Fields

<ResponseField name="success" type="boolean">
  Indicates whether the request was successful
</ResponseField>

<ResponseField name="conversation_id" type="string">
  The UUID of the conversation. Use this to track or reference the conversation later.
</ResponseField>

<ResponseField name="customer_identifier" type="string">
  The customer identifier provided in the request
</ResponseField>

<ResponseField name="reply" type="string">
  The AI-generated response to the customer's message
</ResponseField>

<ResponseField name="function_calls" type="array">
  Array of function calls made by the assistant while processing the message. Empty array if no functions were called.

  <Expandable title="Function call object properties">
    <ResponseField name="name" type="string">
      The name of the function that was called
    </ResponseField>

    <ResponseField name="arguments" type="object">
      The arguments passed to the function
    </ResponseField>

    <ResponseField name="result" type="object">
      The result returned by the function
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ai_disabled" type="boolean">
  Indicates if AI responses are disabled for this conversation (e.g., due to manual takeover)
</ResponseField>

### Error Responses

<ResponseField name="success" type="boolean">
  Will be `false` when an error occurs
</ResponseField>

<ResponseField name="error" type="string">
  Error message describing what went wrong
</ResponseField>

<ResponseField name="error_code" type="string">
  Machine-readable error code. Possible values:

  * `ASSISTANT_NOT_FOUND` - The assistant ID is invalid or doesn't belong to your account
  * `INSUFFICIENT_BALANCE` - Your account balance is too low to process the message
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.autocalls.ai/api/user/ai/generate-reply" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "assistant_id": 123,
      "customer_identifier": "+14155551234",
      "message": "Hi, I would like to schedule an appointment",
      "variables": {
        "customer_name": "John Smith",
        "source": "whatsapp"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.autocalls.ai/api/user/ai/generate-reply', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      assistant_id: 123,
      customer_identifier: '+14155551234',
      message: 'Hi, I would like to schedule an appointment',
      variables: {
        customer_name: 'John Smith',
        source: 'whatsapp'
      }
    })
  });

  const data = await response.json();
  console.log(data.reply);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://app.autocalls.ai/api/user/ai/generate-reply',
      headers={
          'Authorization': 'Bearer YOUR_API_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'assistant_id': 123,
          'customer_identifier': '+14155551234',
          'message': 'Hi, I would like to schedule an appointment',
          'variables': {
              'customer_name': 'John Smith',
              'source': 'whatsapp'
          }
      }
  )

  data = response.json()
  print(data['reply'])
  ```

  ```php PHP theme={null}
  $response = Http::withToken('YOUR_API_TOKEN')
      ->post('https://app.autocalls.ai/api/user/ai/generate-reply', [
          'assistant_id' => 123,
          'customer_identifier' => '+14155551234',
          'message' => 'Hi, I would like to schedule an appointment',
          'variables' => [
              'customer_name' => 'John Smith',
              'source' => 'whatsapp'
          ]
      ]);

  $reply = $response->json()['reply'];
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "customer_identifier": "+14155551234",
    "reply": "Hi John! I'd be happy to help you schedule an appointment. What day and time work best for you?",
    "function_calls": [],
    "ai_disabled": false
  }
  ```

  ```json 200 Success (With Function Calls) theme={null}
  {
    "success": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "customer_identifier": "+14155551234",
    "reply": "I've checked our calendar and we have availability tomorrow at 2 PM and Friday at 10 AM. Which works better for you?",
    "function_calls": [
      {
        "name": "check_availability",
        "arguments": {
          "start_date": "2025-01-08",
          "days": 7
        },
        "result": {
          "slots": ["2025-01-08 14:00", "2025-01-10 10:00"]
        }
      }
    ],
    "ai_disabled": false
  }
  ```

  ```json 404 Assistant Not Found theme={null}
  {
    "success": false,
    "error": "Assistant not found or does not belong to you",
    "error_code": "ASSISTANT_NOT_FOUND"
  }
  ```

  ```json 402 Insufficient Balance theme={null}
  {
    "success": false,
    "error": "Insufficient balance. Please top up your account.",
    "error_code": "INSUFFICIENT_BALANCE"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The assistant id field is required.",
    "errors": {
      "assistant_id": ["The assistant id field is required."]
    }
  }
  ```

  ```json 429 Rate Limited theme={null}
  {
    "message": "Too Many Attempts.",
    "retry_after": 60
  }
  ```
</ResponseExample>

## Use Cases

### Multi-Channel AI Responses

Use this endpoint to add AI responses to any messaging platform:

1. Receive a message from WhatsApp, Facebook, SMS, or any other channel
2. Call this endpoint with the message and customer identifier
3. Send the AI response back through the original channel

### CRM Integration

Integrate AI responses into your CRM or helpdesk:

1. Use the CRM contact ID as the `customer_identifier`
2. Pass customer data as `variables` for personalized responses
3. The conversation persists across sessions using the same identifier

### Custom Chat Interfaces

Build your own chat interface powered by your Autocalls assistant:

1. Generate a unique identifier for each user session
2. Send messages through this endpoint
3. Display the AI responses in your interface

## Conversation Persistence

Conversations are automatically persisted based on the `assistant_id` and `customer_identifier` combination:

* **Same identifier**: Messages are added to the existing conversation, maintaining full context
* **New identifier**: A new conversation is created for the customer
* **Variables merge**: When variables are provided, they are merged with existing conversation variables

## Best Practices

1. **Use consistent identifiers**: Always use the same format for customer identifiers (e.g., always E.164 for phone numbers)
2. **Pass relevant context**: Use the `variables` field to provide customer data that helps the AI personalize responses
3. **Handle rate limits**: Implement retry logic with exponential backoff for rate-limited requests
4. **Store conversation IDs**: Save the returned `conversation_id` for later reference or debugging
5. **Monitor costs**: Track usage to manage costs, especially for high-volume integrations


# Create assistant
Source: https://docs.autocalls.ai/api-reference/assistants/create-assistant

POST /user/assistant
Create a new AI assistant with specified configuration

This endpoint allows you to create a new AI assistant with comprehensive configuration options.

## Engine Modes

The API supports three engine modes, each with different capabilities:

| Mode         | Description                          | Required Fields       |
| ------------ | ------------------------------------ | --------------------- |
| `pipeline`   | Traditional STT → LLM → TTS pipeline | `llm_model_id`        |
| `multimodal` | Real-time multimodal AI              | `multimodal_model_id` |
| `dualplex`   | Multimodal brain + custom TTS voice  | `multimodal_model_id` |

### Request Body

#### Core Required Fields

<ParamField type="string">
  The name of the assistant (max 255 characters)
</ParamField>

<ParamField type="integer">
  The voice ID to use for the assistant. Use the [Get Voices](/api-reference/assistants/get-voices) endpoint with the `mode` parameter to get compatible voices for your engine mode.
</ParamField>

<ParamField type="integer">
  The language ID for the assistant. Use the [Get Languages](/api-reference/assistants/get-languages) endpoint to get available languages.
</ParamField>

<ParamField type="string">
  The assistant type. Options: `inbound`, `outbound`
</ParamField>

<ParamField type="string">
  The engine mode. Options: `pipeline`, `multimodal`, `dualplex`
</ParamField>

<ParamField type="string">
  The timezone for the assistant (e.g., "Europe/Bucharest", "America/New\_York")
</ParamField>

<ParamField type="string">
  The initial message the assistant will speak when the call starts (max 200 characters)
</ParamField>

<ParamField type="string">
  The system prompt that defines the assistant's behavior and personality
</ParamField>

#### Mode-Specific Fields

<ParamField type="integer">
  The LLM model ID to use. **Required for `pipeline` mode.**

  Use the [Get Models](/api-reference/assistants/get-models) endpoint to get available models.
</ParamField>

<ParamField type="integer">
  The multimodal model ID. **Required for `multimodal` and `dualplex` modes.**

  For Dualplex, use [Get Models](/api-reference/assistants/get-models) with `type=dualplex` (GPT Realtime only). Gemini models are Speech-to-speech only and return `422` on Dualplex.
</ParamField>

<ParamField type="integer">
  Fallback LLM model ID for tool calls in multimodal/dualplex modes. Optional.
</ParamField>

<ParamField type="number">
  Turn detection sensitivity for multimodal/dualplex modes (0-1). Default: auto
</ParamField>

#### Secondary Languages

<ParamField type="integer[]">
  Array of additional language IDs the assistant can speak. The assistant will auto-detect and switch languages.

  ```json theme={null}
  "secondary_language_ids": [2, 3, 4]
  ```
</ParamField>

#### Knowledgebase Settings

<ParamField type="integer">
  The knowledgebase ID to attach to this assistant
</ParamField>

<ParamField type="string">
  How to use the knowledgebase. Options:

  * `function_call` - AI calls a function to search (required for multimodal/dualplex)
  * `prompt` - Knowledge is injected into prompt (pipeline only)
</ParamField>

#### Organization

<ParamField type="integer">
  ID of a [folder](/api-reference/folders/create-folder) to place this assistant in. Must belong to your account. Send `null` to leave the assistant uncategorized.
</ParamField>

<ParamField type="integer[]">
  Array of [label](/api-reference/labels/create-label) IDs to apply to this assistant. Each label must belong to your account.

  ```json theme={null}
  "label_ids": [3, 5]
  ```
</ParamField>

#### Phone Number

<ParamField type="integer">
  The ID of a phone number to assign to the assistant. Must belong to your account.

  <Warning>
    For `inbound` assistants, the phone number cannot be a Caller ID type and cannot be already assigned to another inbound assistant.
  </Warning>
</ParamField>

#### Custom Mid-Call Tools

<ParamField type="integer[]">
  Array of custom mid-call tool IDs to attach. Each tool must belong to your account.

  ```json theme={null}
  "tool_ids": [1, 5, 12]
  ```
</ParamField>

#### Built-in Tools

<ParamField type="array">
  Array of built-in tools to enable. Each tool has a `type` and tool-specific fields.

  <Expandable title="Tool types">
    **call\_transfer** - Transfer the call to another phone number

    * `phone_number` (required): Phone number to transfer to (e.g., "+1234567890")
    * `description`: When to transfer the call
    * `custom`: If true, AI can determine transfer number dynamically
    * `timezone`: Timezone for transfer availability
    * `warm_transfer`: Send a message to the customer before transferring (default: `false`)
    * `warm_transfer_message`: Prompt telling the AI what to say before transferring (e.g., "Tell the customer that the call is being transferred.")

    **warm\_call\_transfer** - Warm transfer with supervisor briefing

    * `supervisor_phone` (required): Phone number to dial for the warm transfer (e.g., "+14155552001"). If `custom_sip` is enabled, this is a SIP address or internal extension instead.
    * `outbound_phone_id` (required): ID of the phone number used to dial the supervisor. Use [Get Phone Numbers](/api-reference/assistants/get-phone-numbers) to find available numbers.
    * `description` (required): **When to transfer** — describes when the AI should initiate the warm transfer (e.g., "Transfer the call to a human supervisor when the customer requests to speak with a real person.")
    * `custom_sip`: Enable to enter a custom SIP address or internal extension instead of a phone number (default: `false`)
    * `caller_id_mode`: What phone number the supervisor sees when receiving the call. Options: `outbound_number` (default — shows the outbound phone number), `customer_number` (shows the caller's number), `custom` (shows a custom number)
    * `custom_caller_id`: Custom phone number shown to supervisor. Only used when `caller_id_mode` is `custom`.
    * `hold_music`: Audio played to the caller while on hold. Options: `hold_music` (default — plays default hold music), `none` (silence, no music)
    * `hold_music_volume`: Volume level for hold music, 0-100 (default: `80`)
    * `hold_message`: Message spoken to caller before placing them on hold (default: "Please hold while I connect you with a supervisor.")
    * `summary_instructions`: Instructions for how the AI should brief the supervisor about the call (default: "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).")
    * `briefing_initial_message`: The first message the AI says to the supervisor when they answer (default: "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?")
    * `connected_message`: Message spoken to caller after supervisor is connected (default: "You are now connected with a supervisor. I'll leave you to it.")
    * `ringing_timeout`: Seconds to let the supervisor ring before the transfer is treated as unanswered and the assistant resumes with the caller, 5-120. Omit for the carrier default.
    * `dtmf`: Keypad tones sent as soon as the supervisor line answers, e.g. to dial an extension behind an IVR. Accepts `0-9`, `*`, `#`, `A-D` and `w` (each `w` waits \~0.5 seconds), e.g. `"wwww1234#"`. Add trailing `w` characters to give the extension time to pick up before the briefing starts.

    **end\_call** - End the call programmatically

    * `description`: When the AI should end the call

    **dtmf\_input** - Send DTMF tones (keypad input)

    * `description`: When to use DTMF input (for IVR navigation)

    **collect\_keypad** - Collect keypad input from the caller

    * `timeout`: Seconds to wait for input, 1-30 (default: 5)
    * `stop_key`: Key that ends input. Options: `#` (default), `*`

    **calendar\_integration** - Schedule appointments via Cal.com or Calendly

    * `calendar_type`: Calendar provider. Options: `calcom` (default), `calendly`
    * `description`: When to offer scheduling

    Cal.com fields (`calendar_type: "calcom"`):

    * `calcom_api_key` (required): Your Cal.com API key
    * `calcom_event_slug` (required): The event type slug from Cal.com
    * `calcom_team_slug`: Team slug if the event belongs to a Cal.com team
    * `calcom_endpoint`: Cal.com API region. Options: `us` (default — `https://api.cal.com`), `eu` (`https://api.cal.eu`), `custom` (uses `calcom_custom_endpoint`)
    * `calcom_custom_endpoint`: Custom Cal.com API base URL. Only used when `calcom_endpoint` is `custom` (e.g., `https://my-calcom-instance.com`).
    * `calcom_event_id`: Cal.com event type ID. When provided, the event name is resolved from Cal.com automatically.
    * `calcom_event_name`: Human-readable event name (e.g., `"30 Minute Meeting (30 min)"`). Resolved from Cal.com when `calcom_event_id` is provided, or set explicitly.
    * `calcom_booking_fields`: Array of custom booking fields for the event. Each field has:
      * `slug` (required): Field identifier
      * `type` (required): Field type (e.g., "text", "email", "phone", "select")
      * `label` (required): Display label
      * `required`: Whether the field is required (default: `false`)
      * `options`: Array of options for select fields

    Calendly fields (`calendar_type: "calendly"`):

    * `calendly_api_key` (required): Your Calendly Personal Access Token (PAT). Generate one from your Calendly account: **Integrations & apps → API & webhooks → Generate new token**.
    * `calendly_event_type_uri` (required): Full Calendly event type URI (e.g., `"https://api.calendly.com/event_types/{uuid}"`). Must belong to the authenticated PAT's account.

    **assistant\_transfer** - Hand off the conversation to a different AI assistant mid-call (swaps voice, LLM, and STT to the target assistant)

    * `assistant_id` (required): ID of the target assistant. Must belong to your account.
    * `description`: When to transfer (max 500 chars, default: "Transfer the conversation to this assistant when appropriate.")
    * `message_before_transfer`: Optional message the AI speaks before switching to the target assistant (max 500 chars).
    * `speak_transfer_greeting`: If `true`, the target assistant speaks its configured initial message after the transfer completes (default: `true`).
  </Expandable>

  ```json theme={null}
  "tools": [
    {
      "type": "call_transfer",
      "phone_number": "+1234567890",
      "description": "Transfer when customer requests human support"
    },
    {
      "type": "warm_call_transfer",
      "supervisor_phone": "+1234567891",
      "outbound_phone_id": 7,
      "description": "Transfer the call to a human supervisor when the customer requests to speak with a real person.",
      "custom_sip": false,
      "caller_id_mode": "outbound_number",
      "hold_music": "hold_music",
      "hold_music_volume": 80,
      "hold_message": "Please hold while I connect you with a supervisor.",
      "summary_instructions": "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).",
      "briefing_initial_message": "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?",
      "connected_message": "You are now connected with a supervisor. I'll leave you to it.",
      "ringing_timeout": 30,
      "dtmf": null
    },
    {
      "type": "collect_keypad",
      "timeout": 5,
      "stop_key": "#"
    },
    {
      "type": "assistant_transfer",
      "assistant_id": 14765,
      "description": "Transfer to the Support Assistant when the customer needs technical help.",
      "message_before_transfer": "Sure — let me transfer you to our support specialist.",
      "speak_transfer_greeting": true
    },
    {
      "type": "end_call",
      "description": "End call when customer confirms satisfaction"
    }
  ]
  ```
</ParamField>

#### Voice and TTS Settings

<ParamField type="boolean">
  Whether to enable emotional text-to-speech synthesis
</ParamField>

<ParamField type="number">
  Voice stability setting (0-1). Higher = more consistent voice
</ParamField>

<ParamField type="number">
  Voice similarity setting (0-1). Higher = closer to original voice
</ParamField>

<ParamField type="number">
  Speech speed multiplier (0.7-1.2)
</ParamField>

<ParamField type="number">
  LLM temperature setting (0-1). Lower = more deterministic
</ParamField>

<ParamField type="integer">
  Custom TTS provider ID. Auto-selected based on language if not provided. Use the [Get Synthesizer Providers](/api-reference/assistants/get-synthesizer-providers) endpoint to discover available providers.
</ParamField>

<ParamField type="string">
  Which voice model the provider should use, e.g. `eleven_flash_v2_5` or `sonic-3.5`. Optional — omit it to use the provider's default model, which is the recommended choice.

  Valid values depend on the provider and on the assistant's languages, so read them from the `tts_models` array returned by [Get Synthesizer Providers](/api-reference/assistants/get-synthesizer-providers) with the `language_id` filter applied. Providers whose API takes no model parameter (such as Azure) accept no value here.
</ParamField>

<ParamField type="integer">
  Custom STT provider ID. Auto-selected based on language if not provided. Pipeline mode only. Use the [Get Transcriber Providers](/api-reference/assistants/get-transcriber-providers) endpoint to discover available providers.
</ParamField>

#### Call Behavior Settings

<ParamField type="boolean">
  Whether to allow caller interruptions.

  <Warning>Cannot be disabled for `multimodal` and `dualplex` modes.</Warning>
</ParamField>

<ParamField type="boolean">
  Whether to use filler audio during processing (e.g., "um", "let me check").

  <Warning>Only available for `pipeline` mode.</Warning>
</ParamField>

<ParamField type="object">
  Custom filler word profiles per category. If not provided, defaults are set based on the assistant's language. Each category is an array of short phrases.

  * `positive`: Filler words for positive/affirmative responses (e.g., "Great!", "Perfect!")
  * `negative`: Filler words for negative/neutral responses (e.g., "Hmm.", "Mhm.")
  * `question`: Filler words when processing a question (e.g., "Hmm.", "Let me think.")
  * `neutral`: Filler words for neutral acknowledgments (e.g., "Ok.", "I understand.")

  ```json theme={null}
  "filler_config": {
    "positive": ["Super!", "Great!", "Perfect!"],
    "negative": ["Hmm.", "Mhm.", "I see."],
    "question": ["Hmm.", "Let me check.", "Good question."],
    "neutral": ["Ok.", "I understand.", "Noted."]
  }
  ```
</ParamField>

<ParamField type="boolean">
  Whether to record the call
</ParamField>

<ParamField type="boolean">
  Whether to enable noise cancellation
</ParamField>

<ParamField type="boolean">
  If true, the assistant waits for the customer to speak first
</ParamField>

#### Timing Settings

<ParamField type="integer">
  Maximum call duration in seconds (20-1200)
</ParamField>

<ParamField type="integer">
  Maximum silence duration before re-engagement in seconds (1-360)
</ParamField>

<ParamField type="integer">
  Maximum silence at call start before ending (1-120 seconds). Optional.
</ParamField>

<ParamField type="integer">
  Maximum ringing time before giving up (1-60 seconds)
</ParamField>

#### Re-engagement Settings

<ParamField type="integer">
  Re-engagement interval in seconds (7-600)
</ParamField>

<ParamField type="string">
  Custom prompt for re-engagement messages (max 1000 characters)

  Example: `"Are you still there? Do you have any other questions?"`
</ParamField>

#### Voicemail Settings

<ParamField type="boolean">
  Whether to end call when voicemail is detected
</ParamField>

<ParamField type="string">
  Message to leave on voicemail before hanging up (max 1000 characters)
</ParamField>

#### Endpoint Detection

<ParamField type="string">
  Voice activity detection type. Options: `vad`, `ai`
</ParamField>

<ParamField type="number">
  Endpoint sensitivity level (0-5)
</ParamField>

<ParamField type="number">
  Interrupt sensitivity level (0-5)
</ParamField>

<ParamField type="integer">
  Minimum words before interruption is allowed (0-10). Set to enable.
</ParamField>

#### Ambient Sound

<ParamField type="string">
  Background ambient sound. Options: `off`, `office`, `city`, `forest`, `crowded_room`, `cafe`, `nature`
</ParamField>

<ParamField type="number">
  Ambient sound volume level (0-1)
</ParamField>

#### Webhook Configuration

<ParamField type="boolean">
  Whether webhook notifications are enabled
</ParamField>

<ParamField type="string">
  The webhook URL for post-call notifications. **Required if `is_webhook_active` is true.**
</ParamField>

<ParamField type="boolean">
  Whether to send webhooks only on completed calls (not failed/no-answer)
</ParamField>

<ParamField type="boolean">
  Whether to include recording URL in webhook payload
</ParamField>

#### Post-Call Evaluation

<ParamField type="boolean">
  Whether to enable AI post-call evaluation
</ParamField>

<ParamField type="array">
  Schema definition for post-call data extraction

  <Expandable title="post_call_schema properties">
    <ParamField type="string">
      Field name (3-16 chars, lowercase, alphanumeric and underscores only)
    </ParamField>

    <ParamField type="string">
      Data type. Options: `string`, `number`, `bool`
    </ParamField>

    <ParamField type="string">
      Description of what this field represents (3-255 characters)
    </ParamField>
  </Expandable>

  ```json theme={null}
  "post_call_schema": [
    {"name": "status", "type": "bool", "description": "Was the call objective achieved"},
    {"name": "summary", "type": "string", "description": "Brief summary of the call"}
  ]
  ```
</ParamField>

#### Variables

<ParamField type="object">
  Key-value pairs of custom variables accessible in prompts via `{{variable_name}}`

  ```json theme={null}
  "variables": {
    "company_name": "Acme Corp",
    "product": "Premium Widget",
    "support_email": "support@acme.com"
  }
  ```
</ParamField>

#### Conversation Ended Settings

<ParamField type="integer">
  Minutes of chat inactivity before the conversation is considered ended (1-1440)
</ParamField>

<ParamField type="boolean">
  Whether to allow re-triggering the conversation after it ends due to inactivity
</ParamField>

<ParamField type="string">
  Webhook URL called when a chat conversation ends due to inactivity. Separate from the main call webhook.
</ParamField>

***

## Example Requests

### Pipeline Mode Assistant

```json theme={null}
{
  "name": "Sales Assistant",
  "voice_id": 1,
  "language_id": 1,
  "type": "outbound",
  "mode": "pipeline",
  "timezone": "Europe/Bucharest",
  "initial_message": "Hello! How can I help you today?",
  "system_prompt": "You are a professional sales assistant...",
  "llm_model_id": 2,
  "secondary_language_ids": [2, 3],
  "knowledgebase_id": 1,
  "knowledgebase_mode": "prompt",
  "fillers": true,
  "filler_config": {
    "positive": ["Great!", "Perfect!", "Awesome!"],
    "negative": ["Hmm.", "I see."],
    "question": ["Good question.", "Let me check."],
    "neutral": ["Ok.", "Noted.", "I understand."]
  },
  "tool_ids": [1, 5],
  "tools": [
    {
      "type": "end_call",
      "description": "End call when customer is satisfied"
    },
    {
      "type": "call_transfer",
      "phone_number": "+1234567890",
      "description": "Transfer to support"
    },
    {
      "type": "warm_call_transfer",
      "supervisor_phone": "+1234567891",
      "outbound_phone_id": 7,
      "description": "Transfer the call to a human supervisor when the customer requests to speak with a real person.",
      "custom_sip": false,
      "caller_id_mode": "outbound_number",
      "hold_music": "hold_music",
      "hold_music_volume": 80,
      "hold_message": "Please hold while I connect you with a supervisor.",
      "summary_instructions": "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).",
      "briefing_initial_message": "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?",
      "connected_message": "You are now connected with a supervisor. I'll leave you to it.",
      "ringing_timeout": 30,
      "dtmf": null
    },
    {
      "type": "collect_keypad",
      "timeout": 5,
      "stop_key": "#"
    }
  ],
  "reengagement_interval": 20,
  "reengagement_prompt": "Are you still there?"
}
```

### Multimodal Mode Assistant

```json theme={null}
{
  "name": "Support Bot",
  "voice_id": 41,
  "language_id": 1,
  "type": "inbound",
  "mode": "multimodal",
  "timezone": "America/New_York",
  "initial_message": "Hi! Welcome to support.",
  "system_prompt": "You are a helpful support agent...",
  "multimodal_model_id": 1,
  "chat_llm_fallback_id": 2,
  "turn_detection_threshold": 0.7,
  "knowledgebase_id": 1,
  "knowledgebase_mode": "function_call",
  "tts_emotion_enabled": false
}
```

### Dualplex Mode Assistant

```json theme={null}
{
  "name": "Premium Agent",
  "voice_id": 1,
  "language_id": 2,
  "type": "outbound",
  "mode": "dualplex",
  "timezone": "Europe/Bucharest",
  "initial_message": "Buna ziua!",
  "system_prompt": "Esti un asistent profesionist...",
  "multimodal_model_id": 4,
  "chat_llm_fallback_id": 2,
  "secondary_language_ids": [1, 3],
  "knowledgebase_id": 1,
  "knowledgebase_mode": "function_call",
  "ambient_sound": "office",
  "ambient_sound_volume": 0.3
}
```

***

## Response

<ResponseField name="message" type="string">
  Success message confirming assistant creation
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the created assistant
    </ResponseField>

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

    <ResponseField name="status" type="string">
      The current status (`inactive` for new assistants)
    </ResponseField>

    <ResponseField name="type" type="string">
      The type (`inbound` or `outbound`)
    </ResponseField>

    <ResponseField name="mode" type="string">
      The engine mode (`pipeline`, `multimodal`, or `dualplex`)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Success Response theme={null}
  {
    "message": "Assistant created successfully",
    "data": {
      "id": 789,
      "name": "Sales Assistant",
      "status": "inactive",
      "type": "outbound",
      "mode": "pipeline"
    }
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "Validation failed",
    "errors": {
      "name": ["The name field is required."],
      "voice_id": ["The selected voice is not compatible with the chosen engine type."],
      "knowledgebase_mode": ["Only function_call mode is available for multimodal assistants."]
    }
  }
  ```
</ResponseExample>

***

## Notes

* All required fields must be provided for successful assistant creation
* Use the Get Voices endpoint with `mode` parameter to get compatible voices
* For multimodal/dualplex modes, `knowledgebase_mode` must be `function_call`
* For multimodal/dualplex modes, `allow_interruptions` is always enabled
* Fillers are only available in pipeline mode
* The assistant is created with `inactive` status by default


# Delete assistant
Source: https://docs.autocalls.ai/api-reference/assistants/delete-assistant

DELETE /user/assistant/{id}
Delete a specific AI assistant

This endpoint allows you to permanently delete an AI assistant that belongs to the authenticated user.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the assistant to delete
</ParamField>

### Response

<ResponseField name="message" type="string">
  Confirmation message indicating the assistant was deleted successfully
</ResponseField>

### Error Responses

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message when the assistant is not found or doesn't belong to the authenticated user
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="500 Internal Server Error">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message indicating assistant deletion failure
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "message": "Assistant deleted successfully"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Assistant not found"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "message": "Assistant deletion failed"
  }
  ```
</ResponseExample>

### Notes

* Only assistants that belong to the authenticated user can be deleted
* Once an assistant is deleted, it cannot be recovered
* This action will permanently remove the assistant and all its configuration
* If the assistant is currently handling active calls, those calls may be affected


# Disable conversation ended webhook
Source: https://docs.autocalls.ai/api-reference/assistants/disable-conversation-ended-webhook

POST /user/assistants/disable-conversation-ended-webhook
Disable conversation ended webhook notifications for an assistant

This endpoint disables conversation ended webhook notifications for an assistant, stopping the delivery of updates when chat conversations end.

### Request Body

<ParamField type="integer">
  The ID of the assistant to disable the conversation ended webhook for
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message confirming webhook was disabled
</ResponseField>

<ResponseField name="data" type="array">
  Empty array (reserved for future use)
</ResponseField>

### Error Responses

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message when the assistant is not found or doesn't belong to the authenticated user
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="422 Validation Error">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message indicating validation failure
    </ResponseField>

    <ResponseField name="errors" type="object">
      Detailed validation errors for each field
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "message": "Conversation ended webhook disabled successfully",
    "data": []
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Assistant not found"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "assistant_id": [
        "The assistant id field is required."
      ]
    }
  }
  ```
</ResponseExample>


# Disable assistant inbound webhook
Source: https://docs.autocalls.ai/api-reference/assistants/disable-inbound-webhook

POST /user/assistants/disable-inbound-webhook
Disable inbound webhook notifications for a specific assistant

This endpoint disables inbound webhook notifications for an assistant, stopping the delivery of real-time updates about inbound call completions and data.

### Request Body

<ParamField type="integer">
  The ID of the assistant to disable webhook for
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message confirming webhook was disabled
</ResponseField>

<ResponseField name="data" type="array">
  Empty array (reserved for future use)
</ResponseField>

### Error Responses

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message when the assistant is not found or doesn't belong to the authenticated user
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="422 Validation Error">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message indicating validation failure
    </ResponseField>

    <ResponseField name="errors" type="object">
      Detailed validation errors for each field
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "message": "Inbound webhook disabled successfully",
    "data": []
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Assistant not found"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "assistant_id": [
        "The assistant id field is required."
      ]
    }
  }
  ```
</ResponseExample>


# Disable assistant webhook
Source: https://docs.autocalls.ai/api-reference/assistants/disable-webhook

POST /user/assistants/disable-webhook
Disable webhook notifications for a specific assistant

This endpoint disables webhook notifications for an assistant, stopping all real-time updates about call completions and data.

### Request Body

<ParamField type="integer">
  The ID of the assistant to disable webhook for
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message confirming webhook was disabled
</ResponseField>

<ResponseField name="data" type="array">
  Empty array (reserved for future use)
</ResponseField>

### Error Responses

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message when the assistant is not found or doesn't belong to the authenticated user
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="422 Validation Error">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message indicating validation failure
    </ResponseField>

    <ResponseField name="errors" type="object">
      Detailed validation errors for each field
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "message": "Webhook disabled successfully",
    "data": []
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Assistant not found"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "assistant_id": [
        "The assistant id field is required."
      ]
    }
  }
  ```
</ResponseExample>

### Webhook Behavior

When webhook is disabled:

* The assistant will stop sending HTTP POST requests to your webhook URL
* Both `is_webhook_active` is set to `false` and `webhook_url` is set to `null`
* Any ongoing calls will complete normally, but no webhook notifications will be sent
* Call data will still be available through the API calls endpoints

### Notes

* The assistant must belong to the authenticated user
* This completely removes the webhook configuration from the assistant
* You can later re-enable webhooks using the enable webhook endpoint with a new URL
* Disabling webhooks does not affect call recording or data collection


# Enable conversation ended webhook
Source: https://docs.autocalls.ai/api-reference/assistants/enable-conversation-ended-webhook

POST /user/assistants/enable-conversation-ended-webhook
Enable webhook notifications when a chat conversation ends

This endpoint enables conversation ended webhook notifications for an assistant, allowing you to receive real-time updates when a chat conversation (WhatsApp or Web Widget) ends. The webhook includes the full transcript, extracted variables, and customer information.

### Request Body

<ParamField type="integer">
  The ID of the assistant to enable the conversation ended webhook for
</ParamField>

<ParamField type="string">
  The URL where webhook notifications will be sent when a conversation ends
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message confirming webhook was enabled
</ResponseField>

<ResponseField name="data" type="array">
  Empty array (reserved for future use)
</ResponseField>

### Error Responses

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message when the assistant is not found or doesn't belong to the authenticated user
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="422 Validation Error">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message indicating validation failure
    </ResponseField>

    <ResponseField name="errors" type="object">
      Detailed validation errors for each field
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "message": "Conversation ended webhook enabled successfully",
    "data": []
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Assistant not found"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "assistant_id": [
        "The assistant id field is required."
      ],
      "webhook_url": [
        "The webhook url field is required."
      ]
    }
  }
  ```
</ResponseExample>


# Enable assistant inbound webhook
Source: https://docs.autocalls.ai/api-reference/assistants/enable-inbound-webhook

POST /user/assistants/enable-inbound-webhook
Enable inbound webhook notifications for a specific assistant

This endpoint enables inbound webhook notifications for an assistant, allowing you to receive real-time updates about inbound call completions and data.

### Request Body

<ParamField type="integer">
  The ID of the assistant to enable webhook for
</ParamField>

<ParamField type="string">
  The URL where webhook notifications will be sent
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message confirming webhook was enabled
</ResponseField>

<ResponseField name="data" type="array">
  Empty array (reserved for future use)
</ResponseField>

### Error Responses

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message when the assistant is not found or doesn't belong to the authenticated user
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="422 Validation Error">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message indicating validation failure
    </ResponseField>

    <ResponseField name="errors" type="object">
      Detailed validation errors for each field
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "message": "Webhook enabled successfully",
    "data": []
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Assistant not found"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "assistant_id": [
        "The assistant id field is required."
      ],
      "webhook_url": [
        "The webhook url field is required."
      ]
    }
  }
  ```
</ResponseExample>


# List assistants
Source: https://docs.autocalls.ai/api-reference/assistants/get-assistants

GET /user/assistants/get
List all assistants for the authenticated user with pagination

This endpoint allows you to retrieve all AI assistants belonging to the authenticated user.

### Query Parameters

<ParamField type="integer">
  Number of assistants per page (1-100, default: 10)
</ParamField>

<ParamField type="integer">
  Page number (default: 1)
</ParamField>

### Response fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the assistant
    </ResponseField>

    <ResponseField name="user_id" type="integer">
      The ID of the user who owns this assistant
    </ResponseField>

    <ResponseField name="phone_number_id" type="integer">
      The ID of the phone number assigned to the assistant
    </ResponseField>

    <ResponseField name="engine_id" type="integer">
      Engine ID
    </ResponseField>

    <ResponseField name="synthesizer_id" type="integer">
      Synthesizer ID
    </ResponseField>

    <ResponseField name="transcriber_id" type="integer">
      Transcriber ID
    </ResponseField>

    <ResponseField name="voice_id" type="integer">
      The ID of the voice used by the assistant
    </ResponseField>

    <ResponseField name="instance_id" type="integer">
      The instance ID for the assistant
    </ResponseField>

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

    <ResponseField name="variables" type="object">
      Custom variables defined for the assistant
    </ResponseField>

    <ResponseField name="post_call_evaluation" type="boolean">
      Whether post-call evaluation is enabled
    </ResponseField>

    <ResponseField name="fillers" type="integer">
      Whether filler audio is enabled (1 = enabled, 0 = disabled)
    </ResponseField>

    <ResponseField name="post_call_schema" type="array">
      Schema definition for post-call data extraction

      <Expandable title="post_call_schema properties">
        <ResponseField name="name" type="string">
          The name of the schema field
        </ResponseField>

        <ResponseField name="type" type="string">
          The data type (string, number, bool)
        </ResponseField>

        <ResponseField name="description" type="string">
          Description of what this field represents
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tools" type="array">
      Array of tools available to the assistant
    </ResponseField>

    <ResponseField name="is_webhook_active" type="boolean">
      Whether webhook notifications are enabled
    </ResponseField>

    <ResponseField name="webhook_url" type="string">
      The webhook URL for post-call notifications
    </ResponseField>

    <ResponseField name="inbound_webhook_url" type="string">
      The webhook URL for inbound call notifications
    </ResponseField>

    <ResponseField name="language" type="string">
      Language
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of assistant (inbound or outbound)
    </ResponseField>

    <ResponseField name="status" type="string">
      The current status of the assistant (active or inactive)
    </ResponseField>

    <ResponseField name="max_duration" type="integer">
      Maximum call duration in seconds
    </ResponseField>

    <ResponseField name="record" type="boolean">
      Whether to record calls
    </ResponseField>

    <ResponseField name="initial_message" type="string">
      The initial message the assistant will speak
    </ResponseField>

    <ResponseField name="system_prompt" type="string">
      The system prompt that defines the assistant's behavior
    </ResponseField>

    <ResponseField name="flows_platform_id" type="integer">
      ID for flows platform integration
    </ResponseField>

    <ResponseField name="timezone" type="string">
      The timezone setting for the assistant
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The date and time when the assistant was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      The date and time when the assistant was last updated
    </ResponseField>

    <ResponseField name="max_silence_duration" type="integer">
      Maximum silence duration in seconds before re-engagement
    </ResponseField>

    <ResponseField name="reengagement_interval" type="integer">
      Re-engagement interval in seconds
    </ResponseField>

    <ResponseField name="deleted_at" type="string">
      Soft deletion timestamp (null if not deleted)
    </ResponseField>

    <ResponseField name="end_call_on_voicemail" type="integer">
      Whether to end call when voicemail is detected (1 = yes, 0 = no)
    </ResponseField>

    <ResponseField name="llm_temperature" type="string">
      LLM temperature setting as string
    </ResponseField>

    <ResponseField name="voice_stability" type="string">
      Voice stability setting as string
    </ResponseField>

    <ResponseField name="voice_similarity" type="string">
      Voice similarity setting as string
    </ResponseField>

    <ResponseField name="allow_interruptions" type="boolean">
      Whether to allow caller interruptions
    </ResponseField>

    <ResponseField name="enable_noise_cancellation" type="boolean">
      Whether noise cancellation is enabled
    </ResponseField>

    <ResponseField name="endpoint_sensitivity" type="number">
      Endpoint sensitivity level
    </ResponseField>

    <ResponseField name="speech_speed" type="string">
      Speech speed multiplier as string
    </ResponseField>

    <ResponseField name="endpoint_type" type="string">
      Voice activity detection type (vad or ai)
    </ResponseField>

    <ResponseField name="wait_for_customer" type="boolean">
      Whether to wait for customer to speak first
    </ResponseField>

    <ResponseField name="mode" type="string">
      The engine mode (pipeline or multimodal)
    </ResponseField>

    <ResponseField name="language_id" type="integer">
      The ID of the language used by the assistant
    </ResponseField>

    <ResponseField name="transcriber_provider_id" type="integer">
      ID of the transcriber provider
    </ResponseField>

    <ResponseField name="synthesizer_provider_id" type="integer">
      ID of the synthesizer provider
    </ResponseField>

    <ResponseField name="llm_model_id" type="integer">
      ID of the LLM model used
    </ResponseField>

    <ResponseField name="multimodal_model_id" type="integer">
      ID of the multimodal model used
    </ResponseField>

    <ResponseField name="ambient_sound" type="string">
      Ambient sound setting
    </ResponseField>

    <ResponseField name="uuid" type="string">
      Unique UUID for the assistant
    </ResponseField>

    <ResponseField name="send_webhook_only_on_completed" type="boolean">
      Whether to send webhooks only on completed calls
    </ResponseField>

    <ResponseField name="include_recording_in_webhook" type="boolean">
      Whether to include recording URL in webhook payload
    </ResponseField>

    <ResponseField name="interrupt_sensitivity" type="number">
      Interrupt sensitivity level
    </ResponseField>

    <ResponseField name="filler_config" type="object">
      Configuration for filler audio responses

      <Expandable title="filler_config properties">
        <ResponseField name="neutral" type="array">
          Array of neutral filler responses
        </ResponseField>

        <ResponseField name="negative" type="array">
          Array of negative filler responses
        </ResponseField>

        <ResponseField name="positive" type="array">
          Array of positive filler responses
        </ResponseField>

        <ResponseField name="question" type="array">
          Array of question filler responses
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="knowledgebase_id" type="integer">
      ID of the associated knowledge base
    </ResponseField>

    <ResponseField name="knowledgebase_mode" type="string">
      Knowledge base mode setting
    </ResponseField>

    <ResponseField name="min_interrupt_words" type="integer">
      Minimum number of words before interruption is allowed
    </ResponseField>

    <ResponseField name="ambient_sound_volume" type="string">
      Ambient sound volume level as string
    </ResponseField>

    <ResponseField name="widget_settings" type="object">
      Settings for web widget integration
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="current_page" type="integer">
  The current page number
</ResponseField>

<ResponseField name="per_page" type="integer">
  Number of items per page
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of assistants
</ResponseField>

<ResponseField name="last_page" type="integer">
  The last page number
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 127,
        "user_id": 1,
        "phone_number_id": 45,
        "engine_id": null,
        "synthesizer_id": null,
        "transcriber_id": null,
        "voice_id": 8,
        "instance_id": 1,
        "name": "Sales Outreach Assistant",
        "variables": {
          "company_name": "Your Company",
          "product_line": "Premium Services",
          "rep_name": "Assistant"
        },
        "post_call_evaluation": true,
        "fillers": 1,
        "post_call_schema": [
          {
            "name": "interest_level",
            "type": "string",
            "description": "Customer's level of interest (high, medium, low)"
          },
          {
            "name": "budget_qualified",
            "type": "bool",
            "description": "Whether the prospect has adequate budget"
          },
          {
            "name": "follow_up_date",
            "type": "string",
            "description": "Preferred date for follow-up contact"
          }
        ],
        "tools": [],
        "is_webhook_active": true,
        "webhook_url": "https://yourcompany.com/api/webhooks/sales-calls",
        "inbound_webhook_url": null,
        "language": null,
        "type": "outbound",
        "status": "active",
        "max_duration": 900,
        "record": true,
        "initial_message": "Hi, this is an assistant from Your Company. I hope I'm catching you at a good time. How are you doing today?",
        "system_prompt": "You are a sales representative for Your Company. Be professional, friendly, and focus on qualifying leads for premium services.",
        "flows_platform_id": null,
        "timezone": "America/Los_Angeles",
        "created_at": "2025-07-15T14:32:15.000000Z",
        "updated_at": "2025-08-02T09:18:42.000000Z",
        "max_silence_duration": 25,
        "reengagement_interval": 45,
        "deleted_at": null,
        "end_call_on_voicemail": 1,
        "llm_temperature": "0.35",
        "voice_stability": "0.75",
        "voice_similarity": "0.85",
        "allow_interruptions": true,
        "enable_noise_cancellation": true,
        "endpoint_sensitivity": 1.8,
        "speech_speed": "1.10",
        "endpoint_type": "vad",
        "wait_for_customer": true,
        "mode": "pipeline",
        "language_id": 1,
        "transcriber_provider_id": null,
        "synthesizer_provider_id": null,
        "llm_model_id": 3,
        "multimodal_model_id": null,
        "ambient_sound": "office",
        "uuid": "a7b3c942-5f1e-4d28-8c59-2e4f7a8b9c3d",
        "send_webhook_only_on_completed": true,
        "include_recording_in_webhook": true,
        "interrupt_sensitivity": 1.2,
        "filler_config": {
          "neutral": [
            "I see.",
            "Understood.",
            "Right.",
            "Got it.",
            "Okay."
          ],
          "negative": [
            "I understand.",
            "Hmm.",
            "I see.",
            "Okay."
          ],
          "positive": [
            "Excellent!",
            "That's great!",
            "Wonderful!",
            "Perfect!"
          ],
          "question": [
            "Let me think...",
            "Good question.",
            "Hmm.",
            "Right."
          ]
        },
        "knowledgebase_id": 12,
        "knowledgebase_mode": "hybrid",
        "min_interrupt_words": 3,
        "ambient_sound_volume": "0.30",
        "widget_settings": {
          "theme": "modern",
          "color": "#2563eb",
          "position": "bottom-right"
        }
      }
    ],
    "first_page_url": "https://app.autocalls.ai/api/user/assistants/get?page=1",
    "from": 1,
    "last_page": 5,
    "last_page_url": "https://app.autocalls.ai/api/user/assistants/get?page=5",
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://app.autocalls.ai/api/user/assistants/get?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://app.autocalls.ai/api/user/assistants/get?page=2",
        "label": "2",
        "active": false
      }
    ],
    "next_page_url": "https://app.autocalls.ai/api/user/assistants/get?page=2",
    "path": "https://app.autocalls.ai/api/user/assistants/get",
    "per_page": 10,
    "prev_page_url": null,
    "to": 10,
    "total": 47
  }
  ```
</ResponseExample>


# Get available languages
Source: https://docs.autocalls.ai/api-reference/assistants/get-languages

GET /user/assistants/languages
Retrieve all available languages for assistant configuration

This endpoint returns a list of all available languages that can be used when creating or updating assistants.

### Response fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the language
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the language
    </ResponseField>

    <ResponseField name="iso_2" type="string">
      The ISO 639-1 two-letter language code
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  [
    {
      "id": 1,
      "name": "English",
      "iso_2": "en"
    },
    {
      "id": 2,
      "name": "Romanian",
      "iso_2": "ro"
    },
    {
      "id": 3,
      "name": "French",
      "iso_2": "fr"
    },
    {
      "id": 4,
      "name": "Spanish",
      "iso_2": "es"
    },
    {
      "id": 5,
      "name": "German",
      "iso_2": "de"
    }
  ]
  ```
</ResponseExample>

### Notes

* Use the `id` field as `language_id` when creating or updating assistants
* Use the `id` field in `secondary_language_ids` array for multi-language assistants
* The `iso_2` code can be useful for language-specific functionality
* All available languages are returned in a single request


# Get available models
Source: https://docs.autocalls.ai/api-reference/assistants/get-models

GET /user/assistants/models
Retrieve available AI models for assistant configuration

This endpoint returns a list of available AI models that can be used when creating or updating assistants.

### Query Parameters

<ParamField type="string">
  The type of models to retrieve based on engine mode:

  * `llm` - LLM models for **pipeline** mode (default)
  * `multimodal` - Multimodal models for **multimodal** mode
  * `dualplex` - Multimodal models for **dualplex** mode
</ParamField>

### Response fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the model
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the model
    </ResponseField>

    <ResponseField name="code" type="string">
      The internal code (only for multimodal/dualplex models)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json LLM Models (type=llm) theme={null}
  [
    {
      "id": 1,
      "name": "GPT-4o-mini"
    },
    {
      "id": 2,
      "name": "GPT-4.1-mini"
    }
  ]
  ```

  ```json Dualplex Models (type=dualplex) theme={null}
  [
    {
      "id": 4,
      "name": "GPT Realtime",
      "code": "gpt-realtime"
    }
  ]
  ```
</ResponseExample>

### Notes

* If no `type` parameter is provided, LLM models are returned by default
* Use `llm_model_id` field when creating **pipeline** assistants
* Use `multimodal_model_id` field when creating **multimodal** or **dualplex** assistants
* `type=dualplex` returns GPT Realtime models only. Gemini native-audio models are Speech-to-speech only (`type=multimodal`) and are rejected on Dualplex create/update.


# Get outbound assistants
Source: https://docs.autocalls.ai/api-reference/assistants/get-outbound-assistants

GET /user/assistants/outbound
Retrieve all outbound assistants for the authenticated user

This endpoint returns a list of all outbound assistants belonging to the authenticated user. Outbound assistants are used for making calls to leads and prospects.

### Response fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the assistant
    </ResponseField>

    <ResponseField name="user_id" type="integer">
      The ID of the user who owns this assistant
    </ResponseField>

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

    <ResponseField name="type" type="string">
      The type of assistant (will always be "outbound" for this endpoint)
    </ResponseField>

    <ResponseField name="mode" type="string">
      The engine mode (`pipeline` or `multimodal`)
    </ResponseField>

    <ResponseField name="status" type="string">
      The current status of the assistant
    </ResponseField>

    <ResponseField name="voice_id" type="integer">
      The ID of the voice used by the assistant
    </ResponseField>

    <ResponseField name="language_id" type="integer">
      The ID of the language used by the assistant
    </ResponseField>

    <ResponseField name="timezone" type="string">
      The timezone setting for the assistant
    </ResponseField>

    <ResponseField name="initial_message" type="string">
      The initial message the assistant will speak
    </ResponseField>

    <ResponseField name="system_prompt" type="string">
      The system prompt that defines the assistant's behavior
    </ResponseField>

    <ResponseField name="variables" type="object">
      Custom variables defined for the assistant
    </ResponseField>

    <ResponseField name="webhook_url" type="string">
      The webhook URL for post-call notifications
    </ResponseField>

    <ResponseField name="is_webhook_active" type="boolean">
      Whether webhook notifications are enabled
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The date and time when the assistant was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      The date and time when the assistant was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  [
    {
      "id": 123,
      "user_id": 1,
      "name": "Sales Outbound Assistant",
      "type": "outbound",
      "mode": "pipeline",
      "status": "active",
      "voice_id": 8,
      "language_id": 1,
      "timezone": "America/New_York",
      "initial_message": "Hi, this is Sarah from Your Company. I hope I'm catching you at a good time. How are you doing today?",
      "system_prompt": "You are a sales representative for Your Company. Be professional, friendly, and focus on qualifying leads.",
      "variables": {
        "company_name": "Your Company",
        "product_line": "Premium Services"
      },
      "webhook_url": "https://yourcompany.com/api/webhooks/outbound-calls",
      "is_webhook_active": true,
      "created_at": "2025-07-15T14:32:15.000000Z",
      "updated_at": "2025-08-02T09:18:42.000000Z"
    },
    {
      "id": 124,
      "user_id": 1,
      "name": "Follow-up Assistant",
      "type": "outbound",
      "mode": "multimodal",
      "status": "inactive",
      "voice_id": 12,
      "language_id": 1,
      "timezone": "America/Los_Angeles",
      "initial_message": "Hello! I'm calling to follow up on our previous conversation. Do you have a few minutes to chat?",
      "system_prompt": "You are a follow-up specialist. Be warm and professional while gathering feedback and next steps.",
      "variables": {
        "purpose": "follow_up",
        "max_duration": "5_minutes"
      },
      "webhook_url": null,
      "is_webhook_active": false,
      "created_at": "2025-07-20T10:15:30.000000Z",
      "updated_at": "2025-07-25T16:45:22.000000Z"
    }
  ]
  ```
</ResponseExample>

### Notes

* This endpoint only returns assistants with type "outbound"
* All assistants belonging to the authenticated user are returned (no pagination)
* Use these assistants with the make call endpoint to initiate outbound calls
* Outbound assistants can be used for sales calls, follow-ups, surveys, and other proactive calling scenarios


# Get available phone numbers
Source: https://docs.autocalls.ai/api-reference/assistants/get-phone-numbers

GET /user/assistants/phone-numbers
Retrieve all available phone numbers for assistant assignment

This endpoint returns a list of phone numbers owned by the authenticated user that can be assigned to assistants, with optional filtering by assistant type.

### Query Parameters

<ParamField type="string">
  Filter phone numbers by assistant type. Options: `inbound`, `outbound`
</ParamField>

### Response fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the phone number
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The phone number in E.164 format
    </ResponseField>

    <ResponseField name="country_code" type="string">
      The country code for the phone number
    </ResponseField>

    <ResponseField name="type_label" type="string">
      The human-readable type label for the phone number
    </ResponseField>

    <ResponseField name="is_available" type="boolean">
      Whether the phone number is available for assignment (not currently assigned to an inbound assistant)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  [
    {
      "id": 45,
      "phone_number": "+1234567890",
      "country_code": "US",
      "type_label": "Normal",
      "is_available": true
    },
    {
      "id": 46,
      "phone_number": "+1234567891",
      "country_code": "US",
      "type_label": "SIP",
      "is_available": false
    },
    {
      "id": 47,
      "phone_number": "+441234567890",
      "country_code": "GB",
      "type_label": "Caller ID",
      "is_available": true
    }
  ]
  ```
</ResponseExample>

### Notes

* Only phone numbers owned by the authenticated user are returned
* When `type=inbound` is specified, caller ID numbers and already assigned numbers are filtered out
* The `is_available` field indicates if the number can be assigned to a new inbound assistant
* Phone numbers are returned in the values collection format (indexed array)
* Use the `id` field when assigning phone numbers to assistants


# Get synthesizer providers
Source: https://docs.autocalls.ai/api-reference/assistants/get-synthesizer-providers

GET /user/assistants/synthesizer-providers
Retrieve available TTS (text-to-speech) synthesizer providers

This endpoint returns a list of available synthesizer providers that can be used when creating or updating assistants. Use the returned `id` as `synthesizer_provider_id` when configuring an assistant.

### Query Parameters

<ParamField type="integer">
  Filter providers by language support. Only returns providers that support the given language. Use the [Get Languages](/api-reference/assistants/get-languages) endpoint to get available language IDs.
</ParamField>

### Response fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the provider. Use this as `synthesizer_provider_id` when creating or updating assistants.
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the provider (e.g., "ElevenLabs", "Azure", "Cartesia")
    </ResponseField>

    <ResponseField name="code" type="string">
      The internal code of the provider
    </ResponseField>

    <ResponseField name="tts_models" type="array">
      The voice models this provider offers. Pass one of these `key` values as `tts_model` when creating or updating an assistant. Empty for providers whose API takes no model parameter (such as Azure).

      When `language_id` is supplied, this list only contains models that can speak that language, so any key returned here is safe to send.

      <Expandable title="properties">
        <ResponseField name="key" type="string">
          The value to send as `tts_model`. This is the vendor's own model id (e.g. `eleven_flash_v2_5`).
        </ResponseField>

        <ResponseField name="name" type="string">
          The display name of the model (e.g. "Flash v2.5")
        </ResponseField>

        <ResponseField name="description" type="string">
          A short summary of the model's trade-offs
        </ResponseField>

        <ResponseField name="is_default" type="boolean">
          Whether this is the model used when `tts_model` is omitted
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  [
    {
      "id": 1,
      "name": "ElevenLabs",
      "code": "elevenlabs",
      "tts_models": [
        {
          "key": "eleven_flash_v2_5",
          "name": "Flash v2.5",
          "description": "Fastest to respond, best for live calls. Speaks 32 languages.",
          "is_default": true
        },
        {
          "key": "eleven_v3_conversational",
          "name": "v3 Conversational",
          "description": "More natural and expressive, slightly slower to respond. Speaks every language we offer.",
          "is_default": false
        }
      ]
    },
    {
      "id": 2,
      "name": "Azure",
      "code": "azure",
      "tts_models": []
    },
    {
      "id": 3,
      "name": "Cartesia",
      "code": "cartesia",
      "tts_models": [
        {
          "key": "sonic-3.5",
          "name": "Sonic 3.5",
          "description": "Proven on live calls. Speaks 42 languages.",
          "is_default": true
        },
        {
          "key": "sonic-3.6",
          "name": "Sonic 3.6",
          "description": "Most natural and expressive. Adds Odia and Urdu.",
          "is_default": false
        }
      ]
    }
  ]
  ```

  ```json 200 Filtered by language (Hebrew) theme={null}
  [
    {
      "id": 1,
      "name": "ElevenLabs",
      "code": "elevenlabs",
      "tts_models": [
        {
          "key": "eleven_v3_conversational",
          "name": "v3 Conversational",
          "description": "More natural and expressive, slightly slower to respond. Speaks every language we offer.",
          "is_default": false
        }
      ]
    },
    {
      "id": 3,
      "name": "Cartesia",
      "code": "cartesia",
      "tts_models": [
        {
          "key": "sonic-3.5",
          "name": "Sonic 3.5",
          "description": "Proven on live calls. Speaks 42 languages.",
          "is_default": true
        },
        {
          "key": "sonic-3.6",
          "name": "Sonic 3.6",
          "description": "Most natural and expressive. Adds Odia and Urdu.",
          "is_default": false
        }
      ]
    }
  ]
  ```
</ResponseExample>

### Notes

* If no `language_id` filter is provided, all providers are returned
* Not all providers support all languages — use the `language_id` filter to get compatible providers
* Synthesizer providers are only relevant for `pipeline` and `dualplex` modes (multimodal mode handles TTS internally)
* If you don't set `synthesizer_provider_id` when creating an assistant, the language's default provider is used
* `tts_model` is optional. Omit it and the provider's default model (`is_default: true`) is used
* A `tts_model` key is only valid for the provider that lists it, and only for languages that model supports. Filtering this endpoint by `language_id` is the reliable way to get a key that will be accepted


# Get transcriber providers
Source: https://docs.autocalls.ai/api-reference/assistants/get-transcriber-providers

GET /user/assistants/transcriber-providers
Retrieve available STT (speech-to-text) transcriber providers

This endpoint returns a list of available transcriber providers that can be used when creating or updating assistants. Use the returned `id` as `transcriber_provider_id` when configuring an assistant.

### Query Parameters

<ParamField type="integer">
  Filter providers by language support. Only returns providers that support the given language. Use the [Get Languages](/api-reference/assistants/get-languages) endpoint to get available language IDs.
</ParamField>

### Response fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the provider. Use this as `transcriber_provider_id` when creating or updating assistants.
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the provider (e.g., "Deepgram", "Azure", "Gladia")
    </ResponseField>

    <ResponseField name="code" type="string">
      The internal code of the provider
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  [
    {
      "id": 1,
      "name": "Deepgram",
      "code": "deepgram"
    },
    {
      "id": 2,
      "name": "Azure",
      "code": "azure"
    },
    {
      "id": 3,
      "name": "Gladia",
      "code": "gladia"
    }
  ]
  ```
</ResponseExample>

### Notes

* If no `language_id` filter is provided, all providers are returned
* Not all providers support all languages — use the `language_id` filter to get compatible providers
* Transcriber providers are only relevant for `pipeline` mode (multimodal and dualplex modes handle STT internally)
* If you don't set `transcriber_provider_id` when creating an assistant, the language's default provider is used


# Get available voices
Source: https://docs.autocalls.ai/api-reference/assistants/get-voices

GET /user/assistants/voices
Retrieve all available voices for assistant configuration

This endpoint returns a list of all available voices that can be used when creating or updating assistants, with optional filtering by assistant mode and language.

### Query Parameters

<ParamField type="string">
  Filter voices by assistant mode. Options: `pipeline`, `multimodal`, `dualplex`
</ParamField>

<ParamField type="integer">
  Filter voices by language ID. Use the [Get Languages](/api-reference/assistants/get-languages) endpoint to get available language IDs.
</ParamField>

<ParamField type="integer">
  Filter voices by TTS provider ID (e.g. ElevenLabs, Cartesia, Azure). Use the [Get Synthesizer Providers](/api-reference/assistants/get-synthesizer-providers) endpoint to get available provider IDs.
</ParamField>

<ParamField type="string">
  Filter voices by gender (e.g., `male`, `female`).
</ParamField>

<ParamField type="string">
  Filter voices by age category (e.g., `Young`, `Middle aged`).
</ParamField>

<ParamField type="string">
  Filter voices by accent (e.g., `American`, `British`).
</ParamField>

<ParamField type="string">
  Free-text search across voice name, accent, age, and gender.
</ParamField>

### Response fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the voice
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the voice
    </ResponseField>

    <ResponseField name="language_id" type="integer">
      The language ID this voice is associated with
    </ResponseField>

    <ResponseField name="gender" type="string">
      The gender of the voice (male/female)
    </ResponseField>

    <ResponseField name="preview_url" type="string">
      URL to an audio sample of the voice. Can be used to let users preview voices before selecting one.
    </ResponseField>

    <ResponseField name="accent" type="string">
      The accent of the voice (e.g., "American", "British"). May be `null`.
    </ResponseField>

    <ResponseField name="age" type="string">
      The age category of the voice (e.g., "Young", "Middle aged"). May be `null`.
    </ResponseField>

    <ResponseField name="synthesizer_provider_id" type="integer">
      The TTS provider ID this voice belongs to. Use the [Get Synthesizer Providers](/api-reference/assistants/get-synthesizer-providers) endpoint to resolve provider names. May be `null`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  [
    {
      "id": 1,
      "name": "Alloy",
      "language_id": 1,
      "gender": "female",
      "preview_url": "https://cdn.openai.com/API/voice-previews/alloy.flac",
      "accent": null,
      "age": "Middle aged",
      "synthesizer_provider_id": null
    },
    {
      "id": 10,
      "name": "Zephyr",
      "language_id": 1,
      "gender": "female",
      "preview_url": "https://gstatic.com/aistudio/voices/samples/Zephyr.wav",
      "accent": null,
      "age": "Middle aged",
      "synthesizer_provider_id": 1
    },
    {
      "id": 11,
      "name": "Puck",
      "language_id": 1,
      "gender": "male",
      "preview_url": "https://gstatic.com/aistudio/voices/samples/Puck.wav",
      "accent": null,
      "age": "Middle aged",
      "synthesizer_provider_id": 1
    }
  ]
  ```
</ResponseExample>

### Notes

* Use the `id` field as `voice_id` when creating or updating assistants
* Filter by `mode` to get only voices compatible with your intended assistant type
* Filter by `language_id` to get voices for a specific language
* Filter by `gender`, `age`, or `accent` to narrow the list, or use `search` for free-text matching across those fields
* If no filters are provided, all available voices are returned
* Only voices that are public or belong to the authenticated user are returned


# Update assistant
Source: https://docs.autocalls.ai/api-reference/assistants/update-assistant

PUT /user/assistant/{id}
Update an existing AI assistant's configuration

This endpoint allows you to update an existing AI assistant's configuration. All fields are optional - only provide the fields you want to update.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the assistant to update
</ParamField>

### Request Body

#### Core Fields

<ParamField type="string">
  The name of the assistant (max 255 characters)
</ParamField>

<ParamField type="integer">
  The voice ID to use for the assistant. Use the [Get Voices](/api-reference/assistants/get-voices) endpoint with the `mode` parameter to get compatible voices for your engine mode.
</ParamField>

<ParamField type="integer">
  The language ID for the assistant. Use the [Get Languages](/api-reference/assistants/get-languages) endpoint to get available languages.
</ParamField>

<ParamField type="string">
  The assistant type. Options: `inbound`, `outbound`
</ParamField>

<ParamField type="string">
  The engine mode. Options: `pipeline`, `multimodal`, `dualplex`

  <Warning>
    Changing the mode will reset mode-specific settings to defaults for the new mode.
  </Warning>
</ParamField>

<ParamField type="string">
  The timezone for the assistant (e.g., "Europe/Bucharest", "America/New\_York")
</ParamField>

<ParamField type="string">
  The initial message the assistant will speak when the call starts (max 200 characters)
</ParamField>

<ParamField type="string">
  The system prompt that defines the assistant's behavior and personality
</ParamField>

#### Mode-Specific Fields

<ParamField type="integer">
  The LLM model ID to use. Only applies to `pipeline` mode.

  Use the [Get Models](/api-reference/assistants/get-models) endpoint to get available models.
</ParamField>

<ParamField type="integer">
  The multimodal model ID. Only applies to `multimodal` and `dualplex` modes.

  Dualplex accepts GPT Realtime only (`type=dualplex`). Gemini is Speech-to-speech only and returns `422` if you set it on a Dualplex assistant.
</ParamField>

<ParamField type="integer">
  Fallback LLM model ID for tool calls in multimodal/dualplex modes. Set to `null` to remove.
</ParamField>

<ParamField type="number">
  Turn detection sensitivity for multimodal/dualplex modes (0-1). Set to `null` for auto.
</ParamField>

#### Secondary Languages

<ParamField type="integer[]">
  Array of additional language IDs the assistant can speak. Replaces existing secondary languages. Pass an empty array `[]` to remove all secondary languages.

  ```json theme={null}
  "secondary_language_ids": [2, 3, 4]
  ```
</ParamField>

#### Knowledgebase Settings

<ParamField type="integer">
  The knowledgebase ID to attach. Set to `null` to remove knowledgebase.
</ParamField>

<ParamField type="string">
  How to use the knowledgebase. Options:

  * `function_call` - AI calls a function to search (required for multimodal/dualplex)
  * `prompt` - Knowledge is injected into prompt (pipeline only)
</ParamField>

#### Organization

<ParamField type="integer">
  ID of a [folder](/api-reference/folders/create-folder) to move this assistant into. Must belong to your account. Set to `null` to make it uncategorized. Omit to leave the folder unchanged.
</ParamField>

<ParamField type="integer[]">
  Array of [label](/api-reference/labels/create-label) IDs for this assistant. Each label must belong to your account. When provided, this **replaces** the assistant's current labels. Omit to leave labels unchanged; send `[]` to remove all labels.

  ```json theme={null}
  "label_ids": [3, 5]
  ```
</ParamField>

#### Phone Number

<ParamField type="integer">
  The ID of a phone number to assign. Set to `null` to unassign. Must belong to your account.

  <Warning>
    For `inbound` assistants, the phone number cannot be a Caller ID type and cannot be already assigned to another inbound assistant.
  </Warning>
</ParamField>

#### Custom Mid-Call Tools

<ParamField type="integer[]">
  Array of custom mid-call tool IDs to sync. **Replaces all existing tool assignments.** Pass an empty array `[]` to remove all tools. Each tool must belong to your account.

  ```json theme={null}
  "tool_ids": [1, 5, 12]
  ```
</ParamField>

#### Built-in Tools

<ParamField type="array">
  Array of built-in tools. **Replaces all existing built-in tools.** Pass an empty array `[]` to remove all tools.

  <Expandable title="Tool types">
    **call\_transfer** - Transfer the call to another phone number

    * `phone_number` (required): Phone number to transfer to
    * `description`: When to transfer the call
    * `custom`: If true, AI can determine transfer number dynamically
    * `timezone`: Timezone for transfer availability
    * `warm_transfer`: Send a message to the customer before transferring (default: `false`)
    * `warm_transfer_message`: Prompt telling the AI what to say before transferring (e.g., "Tell the customer that the call is being transferred.")

    **warm\_call\_transfer** - Warm transfer with supervisor briefing

    * `supervisor_phone` (required): Phone number to dial for the warm transfer (e.g., "+14155552001"). If `custom_sip` is enabled, this is a SIP address or internal extension instead.
    * `outbound_phone_id` (required): ID of the phone number used to dial the supervisor.
    * `description` (required): **When to transfer** — describes when the AI should initiate the warm transfer (e.g., "Transfer the call to a human supervisor when the customer requests to speak with a real person.")
    * `custom_sip`: Enable to enter a custom SIP address or internal extension instead of a phone number (default: `false`)
    * `caller_id_mode`: What phone number the supervisor sees when receiving the call. Options: `outbound_number` (default — shows the outbound phone number), `customer_number` (shows the caller's number), `custom` (shows a custom number)
    * `custom_caller_id`: Custom phone number shown to supervisor. Only used when `caller_id_mode` is `custom`.
    * `hold_music`: Audio played to the caller while on hold. Options: `hold_music` (default — plays default hold music), `none` (silence, no music)
    * `hold_music_volume`: Volume level for hold music, 0-100 (default: `80`)
    * `hold_message`: Message spoken to caller before placing them on hold (default: "Please hold while I connect you with a supervisor.")
    * `summary_instructions`: Instructions for how the AI should brief the supervisor about the call (default: "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).")
    * `briefing_initial_message`: The first message the AI says to the supervisor when they answer (default: "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?")
    * `connected_message`: Message spoken to caller after supervisor is connected (default: "You are now connected with a supervisor. I'll leave you to it.")
    * `ringing_timeout`: Seconds to let the supervisor ring before the transfer is treated as unanswered and the assistant resumes with the caller, 5-120. Omit for the carrier default.
    * `dtmf`: Keypad tones sent as soon as the supervisor line answers, e.g. to dial an extension behind an IVR. Accepts `0-9`, `*`, `#`, `A-D` and `w` (each `w` waits \~0.5 seconds), e.g. `"wwww1234#"`. Add trailing `w` characters to give the extension time to pick up before the briefing starts.

    **end\_call** - End the call programmatically

    * `description`: When the AI should end the call

    **dtmf\_input** - Send DTMF tones (keypad input)

    * `description`: When to use DTMF input (for IVR navigation)

    **collect\_keypad** - Collect keypad input from the caller

    * `timeout`: Seconds to wait for input, 1-30 (default: 5)
    * `stop_key`: Key that ends input. Options: `#` (default), `*`

    **calendar\_integration** - Schedule appointments via Cal.com or Calendly

    * `calendar_type`: Calendar provider. Options: `calcom` (default), `calendly`
    * `description`: When to offer scheduling

    Cal.com fields (`calendar_type: "calcom"`):

    * `calcom_api_key` (required): Your Cal.com API key
    * `calcom_event_slug` (required): The event type slug from Cal.com
    * `calcom_team_slug`: Team slug if the event belongs to a Cal.com team
    * `calcom_endpoint`: Cal.com API region. Options: `us` (default — `https://api.cal.com`), `eu` (`https://api.cal.eu`), `custom` (uses `calcom_custom_endpoint`)
    * `calcom_custom_endpoint`: Custom Cal.com API base URL. Only used when `calcom_endpoint` is `custom` (e.g., `https://my-calcom-instance.com`).
    * `calcom_event_id`: Cal.com event type ID. When provided, the event name is resolved from Cal.com automatically.
    * `calcom_event_name`: Human-readable event name (e.g., `"30 Minute Meeting (30 min)"`). Resolved from Cal.com when `calcom_event_id` is provided, or set explicitly.
    * `calcom_booking_fields`: Array of custom booking fields for the event. Each field has:
      * `slug` (required): Field identifier
      * `type` (required): Field type (e.g., "text", "email", "phone", "select")
      * `label` (required): Display label
      * `required`: Whether the field is required (default: `false`)
      * `options`: Array of options for select fields

    Calendly fields (`calendar_type: "calendly"`):

    * `calendly_api_key` (required): Your Calendly Personal Access Token (PAT). Generate one from your Calendly account: **Integrations & apps → API & webhooks → Generate new token**.
    * `calendly_event_type_uri` (required): Full Calendly event type URI (e.g., `"https://api.calendly.com/event_types/{uuid}"`). Must belong to the authenticated PAT's account.

    **assistant\_transfer** - Hand off the conversation to a different AI assistant mid-call (swaps voice, LLM, and STT to the target assistant)

    * `assistant_id` (required): ID of the target assistant. Must belong to your account and cannot be the assistant being updated (no self-transfer).
    * `description`: When to transfer (max 500 chars, default: "Transfer the conversation to this assistant when appropriate.")
    * `message_before_transfer`: Optional message the AI speaks before switching to the target assistant (max 500 chars).
    * `speak_transfer_greeting`: If `true`, the target assistant speaks its configured initial message after the transfer completes (default: `true`).
  </Expandable>

  ```json theme={null}
  "tools": [
    {
      "type": "dtmf_input",
      "description": "Navigate IVR when needed"
    },
    {
      "type": "warm_call_transfer",
      "supervisor_phone": "+1234567890",
      "outbound_phone_id": 7,
      "description": "Transfer the call to a human supervisor when the customer requests to speak with a real person.",
      "custom_sip": false,
      "caller_id_mode": "outbound_number",
      "hold_music": "hold_music",
      "hold_music_volume": 80,
      "hold_message": "Please hold while I connect you with a supervisor.",
      "summary_instructions": "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).",
      "briefing_initial_message": "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?",
      "connected_message": "You are now connected with a supervisor. I'll leave you to it.",
      "ringing_timeout": 30,
      "dtmf": null
    },
    {
      "type": "collect_keypad",
      "timeout": 5,
      "stop_key": "#"
    },
    {
      "type": "assistant_transfer",
      "assistant_id": 14765,
      "description": "Transfer to the Support Assistant when the customer needs technical help.",
      "message_before_transfer": "Sure — let me transfer you to our support specialist.",
      "speak_transfer_greeting": true
    },
    {
      "type": "end_call",
      "description": "End call when done"
    }
  ]
  ```
</ParamField>

#### Voice and TTS Settings

<ParamField type="boolean">
  Whether to enable emotional text-to-speech synthesis
</ParamField>

<ParamField type="number">
  Voice stability setting (0-1). Higher = more consistent voice
</ParamField>

<ParamField type="number">
  Voice similarity setting (0-1). Higher = closer to original voice
</ParamField>

<ParamField type="number">
  Speech speed multiplier (0.7-1.2)
</ParamField>

<ParamField type="number">
  LLM temperature setting (0-1). Lower = more deterministic
</ParamField>

<ParamField type="integer">
  Custom TTS provider ID. Set to `null` to use language default. Use the [Get Synthesizer Providers](/api-reference/assistants/get-synthesizer-providers) endpoint to discover available providers.
</ParamField>

<ParamField type="string">
  Which voice model the provider should use, e.g. `eleven_flash_v2_5` or `sonic-3.5`. Optional — omit it to leave the current model unchanged, or set it to `null` to fall back to the provider's default.

  Valid values depend on the provider and on the assistant's languages, so read them from the `tts_models` array returned by [Get Synthesizer Providers](/api-reference/assistants/get-synthesizer-providers) with the `language_id` filter applied.

  Sending a model the provider or the assistant's languages don't support fails validation. If you instead omit `tts_model` while changing `language_id`, `synthesizer_provider_id`, or `mode`, the model is reset to the new provider's default for those languages.
</ParamField>

<ParamField type="integer">
  Custom STT provider ID. Pipeline mode only. Set to `null` to use language default. Use the [Get Transcriber Providers](/api-reference/assistants/get-transcriber-providers) endpoint to discover available providers.
</ParamField>

#### Call Behavior Settings

<ParamField type="boolean">
  Whether to allow caller interruptions.

  <Warning>Cannot be disabled for `multimodal` and `dualplex` modes.</Warning>
</ParamField>

<ParamField type="boolean">
  Whether to use filler audio during processing.

  <Warning>Only available for `pipeline` mode.</Warning>
</ParamField>

<ParamField type="object">
  Custom filler word profiles per category. Replaces existing filler config. Each category is an array of short phrases.

  * `positive`: Filler words for positive/affirmative responses
  * `negative`: Filler words for negative/neutral responses
  * `question`: Filler words when processing a question
  * `neutral`: Filler words for neutral acknowledgments

  ```json theme={null}
  "filler_config": {
    "positive": ["Great!", "Perfect!"],
    "negative": ["Hmm.", "I see."],
    "question": ["Good question.", "Let me check."],
    "neutral": ["Ok.", "Noted."]
  }
  ```
</ParamField>

<ParamField type="boolean">
  Whether to record the call
</ParamField>

<ParamField type="boolean">
  Whether to enable noise cancellation
</ParamField>

<ParamField type="boolean">
  If true, the assistant waits for the customer to speak first
</ParamField>

#### Timing Settings

<ParamField type="integer">
  Maximum call duration in seconds (20-1200)
</ParamField>

<ParamField type="integer">
  Maximum silence duration before re-engagement in seconds (1-360)
</ParamField>

<ParamField type="integer">
  Maximum silence at call start before ending (1-120 seconds). Set to `null` to disable.
</ParamField>

<ParamField type="integer">
  Maximum ringing time before giving up (1-60 seconds)
</ParamField>

#### Re-engagement Settings

<ParamField type="integer">
  Re-engagement interval in seconds (7-600)
</ParamField>

<ParamField type="string">
  Custom prompt for re-engagement messages (max 1000 characters). Set to `null` to use default.
</ParamField>

#### Voicemail Settings

<ParamField type="boolean">
  Whether to end call when voicemail is detected
</ParamField>

<ParamField type="string">
  Message to leave on voicemail before hanging up (max 1000 characters). Set to `null` to disable.
</ParamField>

#### Endpoint Detection

<ParamField type="string">
  Voice activity detection type. Options: `vad`, `ai`
</ParamField>

<ParamField type="number">
  Endpoint sensitivity level (0-5)
</ParamField>

<ParamField type="number">
  Interrupt sensitivity level (0-5)
</ParamField>

<ParamField type="integer">
  Minimum words before interruption is allowed (0-10). Set to `null` to disable.
</ParamField>

#### Ambient Sound

<ParamField type="string">
  Background ambient sound. Options: `off`, `office`, `city`, `forest`, `crowded_room`, `cafe`, `nature`
</ParamField>

<ParamField type="number">
  Ambient sound volume level (0-1)
</ParamField>

#### Webhook Configuration

<ParamField type="boolean">
  Whether webhook notifications are enabled
</ParamField>

<ParamField type="string">
  The webhook URL for post-call notifications. Set to `null` to remove.
</ParamField>

<ParamField type="boolean">
  Whether to send webhooks only on completed calls (not failed/no-answer)
</ParamField>

<ParamField type="boolean">
  Whether to include recording URL in webhook payload
</ParamField>

#### Post-Call Evaluation

<ParamField type="boolean">
  Whether to enable AI post-call evaluation
</ParamField>

<ParamField type="array">
  Schema definition for post-call data extraction. Replaces existing schema.

  <Expandable title="post_call_schema properties">
    <ParamField type="string">
      Field name (3-16 chars, lowercase, alphanumeric and underscores only)
    </ParamField>

    <ParamField type="string">
      Data type. Options: `string`, `number`, `bool`
    </ParamField>

    <ParamField type="string">
      Description of what this field represents (3-255 characters)
    </ParamField>
  </Expandable>
</ParamField>

#### Variables

<ParamField type="object">
  Key-value pairs of custom variables. **Replaces all existing variables.**

  ```json theme={null}
  "variables": {
    "company_name": "Acme Corp",
    "product": "Premium Widget"
  }
  ```
</ParamField>

#### Conversation Ended Settings

<ParamField type="integer">
  Minutes of chat inactivity before the conversation is considered ended (1-1440). Set to `null` to disable. Default: `30`
</ParamField>

<ParamField type="boolean">
  Whether to allow re-triggering the conversation after it ends due to inactivity
</ParamField>

<ParamField type="string">
  Webhook URL called when a chat conversation ends due to inactivity. Set to `null` to remove. Separate from the main call webhook.
</ParamField>

***

## Example Requests

### Update Basic Settings

```json theme={null}
{
  "name": "Updated Assistant Name",
  "initial_message": "Hello! How may I assist you?",
  "max_duration": 900
}
```

### Switch to Multimodal Mode

```json theme={null}
{
  "mode": "multimodal",
  "voice_id": 41,
  "multimodal_model_id": 1,
  "chat_llm_fallback_id": 2,
  "knowledgebase_mode": "function_call"
}
```

### Update Tools and Knowledgebase

```json theme={null}
{
  "tool_ids": [1, 5, 12],
  "knowledgebase_id": 3,
  "knowledgebase_mode": "prompt"
}
```

### Update Re-engagement and Voicemail

```json theme={null}
{
  "reengagement_interval": 15,
  "reengagement_prompt": "Are you still there? I'm here to help.",
  "end_call_on_voicemail": true,
  "voice_mail_message": "Hello, please call us back at your convenience."
}
```

### Add Calendar Integration (Cal.com)

```json theme={null}
{
  "tools": [
    {
      "type": "calendar_integration",
      "calendar_type": "calcom",
      "calcom_api_key": "cal_live_xxxxxxxxxxxx",
      "calcom_event_slug": "30min",
      "calcom_event_id": 123456,
      "calcom_event_name": "30 Minute Meeting (30 min)",
      "calcom_endpoint": "us",
      "description": "Offer scheduling when the customer wants to book an appointment"
    }
  ]
}
```

### Add Calendar Integration (Calendly)

```json theme={null}
{
  "tools": [
    {
      "type": "calendar_integration",
      "calendar_type": "calendly",
      "calendly_api_key": "eyJraWQiOiIxY...",
      "calendly_event_type_uri": "https://api.calendly.com/event_types/AAAAAAAAAAAAAAAA",
      "description": "Offer scheduling when the customer wants to book an appointment"
    }
  ]
}
```

### Remove Optional Settings

```json theme={null}
{
  "phone_number_id": null,
  "webhook_url": null,
  "tool_ids": [],
  "secondary_language_ids": []
}
```

***

## Response

<ResponseField name="message" type="string">
  Success message confirming assistant update
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the updated assistant
    </ResponseField>

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

    <ResponseField name="status" type="string">
      The current status of the assistant
    </ResponseField>

    <ResponseField name="type" type="string">
      The type (`inbound` or `outbound`)
    </ResponseField>

    <ResponseField name="mode" type="string">
      The engine mode (`pipeline`, `multimodal`, or `dualplex`)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "message": "Assistant updated successfully",
    "data": {
      "id": 789,
      "name": "Updated Sales Assistant",
      "status": "active",
      "type": "outbound",
      "mode": "pipeline"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Assistant not found"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "Validation failed",
    "errors": {
      "speech_speed": ["The speech speed must be between 0.7 and 1.2."],
      "voice_id": ["The selected voice is not compatible with the chosen engine type."],
      "allow_interruptions": ["Interruptions cannot be disabled in multimodal or dualplex mode."]
    }
  }
  ```

  ```json 422 Invalid Calendly Event URI theme={null}
  {
    "message": "Validation failed",
    "errors": {
      "tools": ["The Calendly event type URI does not belong to this account."]
    }
  }
  ```
</ResponseExample>

***

## Notes

* Only the fields you provide in the request body will be updated
* To remove optional fields, explicitly set them to `null`
* To clear arrays (tools, secondary languages), pass an empty array `[]`
* The assistant must belong to the authenticated user
* Use the Get Voices endpoint with `mode` parameter to get compatible voices
* For multimodal/dualplex modes, `knowledgebase_mode` must be `function_call`
* For multimodal/dualplex modes, `allow_interruptions` cannot be disabled
* Changing the mode resets mode-specific settings (LLM model, multimodal model, providers)


# Authentication
Source: https://docs.autocalls.ai/api-reference/authentication

Learn how to authenticate your API requests

The Autocalls API uses API keys to authenticate requests. You need to include your API key in the header of each request you make to the API.

## Obtaining an API Key

To obtain an API key:

1. Log in to your Autocalls account at [https://app.autocalls.ai](https://app.autocalls.ai)
2. Navigate to the "API Keys" page
3. Click on the "Create new API Key" button
4. Copy your new API key and store it securely

<Warning>
  Keep your API key confidential and secure. Do not share it publicly or commit
  it to version control systems.
</Warning>

## Using the API Key

Include your API key in the `Authorization` header of each request:

```
Authorization: Bearer YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

## Example Request

Here's an example of how to include the API key in a cURL request:

```bash theme={null}
curl -X GET "https://api.autocalls.ai/api/user/campaigns" \
     -H "Authorization: Bearer YOUR_API_KEY"
```

Replace `YOUR_API_KEY` with your actual API key when making requests.


# Create API key
Source: https://docs.autocalls.ai/api-reference/authentication/create-api-key

POST /user/api-keys
Generate a new API key for the authenticated user

This endpoint generates a new API key for the authenticated user. Unlike the login endpoint which creates a session token, this creates a persistent API key that can be used for long-term API access.

<Note>
  This endpoint requires authentication. Use your existing API key or session token to create additional API keys.
</Note>

### Request Body

<ParamField type="string">
  A name/label for the API key (e.g., "Production", "Development", "My App")
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="api_key" type="object">
  The created API key details

  <Expandable title="api_key properties">
    <ResponseField name="name" type="string">
      The name/label of the API key
    </ResponseField>

    <ResponseField name="token" type="string">
      The API key token. **Store this securely** - it will only be shown once.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the API key was created
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "message": "API key created successfully.",
    "api_key": {
      "name": "Production API Key",
      "token": "1|abc123xyz789abcdef...",
      "created_at": "2025-01-08T10:30:00.000000Z"
    }
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The name field is required.",
    "errors": {
      "name": ["The name field is required."]
    }
  }
  ```
</ResponseExample>

### Example Request

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/user/api-keys \
  -H "Authorization: Bearer YOUR_EXISTING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key"
  }'
```

<Warning>
  The API key token is only returned once. Make sure to store it securely. If you lose it, you'll need to create a new one.
</Warning>

### Managing API Keys

* **GET /user/api-keys** - List all API keys for the authenticated user
* **DELETE /user/api-keys/** - Delete a specific API key


# Delete API key
Source: https://docs.autocalls.ai/api-reference/authentication/delete-api-key

DELETE /user/api-keys/{id}
Delete an API key

This endpoint permanently deletes an API key. Any applications using this key will immediately lose access.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the API key to delete
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "message": "API key deleted successfully."
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "API key not found."
  }
  ```
</ResponseExample>

<Warning>
  This action is immediate and cannot be undone. Any applications using this API key will stop working immediately.
</Warning>


# List API keys
Source: https://docs.autocalls.ai/api-reference/authentication/list-api-keys

GET /user/api-keys
Get all API keys for the authenticated user

This endpoint returns a list of all API keys associated with the authenticated user's account.

### Response

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

  <Expandable title="api_key properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the API key
    </ResponseField>

    <ResponseField name="name" type="string">
      The name/label of the API key
    </ResponseField>

    <ResponseField name="last_used_at" type="string">
      ISO 8601 timestamp of when the API key was last used (null if never used)
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the API key was created
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "api_keys": [
      {
        "id": 1,
        "name": "Production API Key",
        "last_used_at": "2025-01-08T15:30:00.000000Z",
        "created_at": "2025-01-01T10:00:00.000000Z"
      },
      {
        "id": 2,
        "name": "Development API Key",
        "last_used_at": null,
        "created_at": "2025-01-05T14:20:00.000000Z"
      }
    ]
  }
  ```

  ```json 200 Empty Response theme={null}
  {
    "api_keys": []
  }
  ```
</ResponseExample>

<Note>
  For security reasons, the actual API key tokens are not returned. Only metadata about the keys is shown.
</Note>


# Apply automation template
Source: https://docs.autocalls.ai/api-reference/automations/apply-automation-template

POST /user/automate/templates/{key}
Create an automation from a ready-made template and prove it with a real test run

This endpoint creates an automation from a template (see [List automation templates](/api-reference/automations/list-automation-templates)), runs a **real test**, and — for assistant-event templates — attaches the automation to the assistant once the test passes. It returns the same envelope as [Create automation](/api-reference/automations/create-automation).

<Warning>
  Templates marked `side_effects: true` really send messages or start calls during their test run — applying them requires `confirm_side_effects: true`, and the test targets the real values you supplied. Never apply a template with example or guessed values.
</Warning>

### Path Parameters

<ParamField type="string">
  The template key (from [List automation templates](/api-reference/automations/list-automation-templates)). An unknown key returns a `404`.
</ParamField>

### Request body

<ParamField type="object">
  The template's parameters as key-value pairs — see the template's `params` list for what each one needs. Missing required parameters return a `422` (`missing_params`) listing exactly what is needed. Max 64 KB.
</ParamField>

<ParamField type="integer">
  The assistant the resulting automation attaches to. Required for templates with `requires_assistant: true`.
</ParamField>

<ParamField type="string">
  A custom name for the automation (max 255 characters); defaults to the template name
</ParamField>

<ParamField type="boolean">
  Required (`true`) for templates marked `side_effects: true`
</ParamField>

### Response

The [Create automation](/api-reference/automations/create-automation) envelope: `automation_id`, `webhook_url` (for webhook-triggered templates such as `lead-intake-webhook` and the mid-call lookup ones; `null` for assistant-event templates), `status` (`active` / `active_untested` / `test_failed`), `test` (`run_status` + per-step outcomes), `response`, `binding`. Returns `201` when the automation is active, `200` when its test run failed.

A template whose test run parks at a Delay step (e.g. `post-call-callback`) reports `run_status: "PAUSED"` — that is success, not a failure: every step before the delay ran, and the run resumes at the target time.

### Error codes (`422`)

Hard failures return `{"message": "...", "error": "<code>", "params": ...}` and nothing is created. Notable codes:

| `error`                                                           | Meaning                                                                                                                                            |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `missing_params`                                                  | Required parameters are missing — the response's `params` array lists their full specs.                                                            |
| `invalid_param_choice`                                            | A parameter references a resource (e.g. a spreadsheet) that does not exist in your connected account — the message lists the real choices by name. |
| `needs_connection` / `needs_reconnection`                         | A required account connection is missing or broken — the message contains the exact steps to fix it in the app (one-time).                         |
| `side_effects_require_confirmation`                               | The template sends for real — retry with `confirm_side_effects: true`.                                                                             |
| `assistant_required` / `assistant_not_found` / `binding_conflict` | Same as [Create automation](/api-reference/automations/create-automation).                                                                         |

<ResponseExample>
  ```json 201 Response (test passed and attached) theme={null}
  {
    "automation_id": "aB3xYz01MnOpQrStUvWxY",
    "webhook_url": null,
    "status": "active",
    "test": {
      "run_status": "SUCCEEDED",
      "steps": []
    },
    "response": null,
    "binding": {
      "type": "post_call",
      "assistant_id": 123,
      "bound": true
    }
  }
  ```

  ```json 422 Response (missing params) theme={null}
  {
    "message": "These values are required: spreadsheet_id. Ask the user for them — never guess or reuse example values.",
    "error": "missing_params",
    "params": [
      {
        "key": "spreadsheet_id",
        "label": "Google Spreadsheet ID",
        "description": "The spreadsheet to append rows to.",
        "required": true,
        "example": "1AbCdEfGhIjKlMnOpQrStUvWxYz"
      }
    ]
  }
  ```

  ```json 404 Response (unknown template) theme={null}
  {
    "message": "No template with that key — call the template list first.",
    "error": "template_not_found",
    "params": null
  }
  ```
</ResponseExample>


# Create automation
Source: https://docs.autocalls.ai/api-reference/automations/create-automation

POST /user/automate/flows
Create an automation from a definition, activate it and prove it with a real test run

This endpoint creates an automation from its definition (a trigger and its chained steps), activates it, executes a **real test run** with your sample payload, and reports the result step by step. The test run is the gate: an automation whose test fails is left disabled, and an assistant-event automation is only attached to the assistant after its test passes.

When a ready-made [template](/api-reference/automations/list-automation-templates) matches what you need, [applying it](/api-reference/automations/apply-automation-template) is simpler than writing a definition from scratch.

<Warning>
  The test run **executes the automation for real**. Definitions containing steps that send messages or emails, or start calls, are refused unless you explicitly pass `confirm_side_effects: true` — and when you do, those steps really send during the test. Point them at recipients you own.
</Warning>

### The definition format

The `flow` object is the automation's definition. The preferred shape is a flat list:

```json theme={null}
{
  "trigger": { ... },
  "steps": [ step1, step2, ... ]
}
```

The steps are chained onto the trigger in the order given. The only nesting you write yourself is inside a step that needs it — a `BRANCH` step's conditional steps go under its `onSuccessAction` / `onFailureAction`. (A hand-nested tree, where each step sits under the previous one's `nextAction`, is also accepted.)

A definition **always replaces the whole automation** — it is never merged. A trigger with no steps is rejected (`no_steps`): an automation that does nothing cannot be activated.

**Supported triggers** (`trigger.settings`):

| Trigger               | `pieceName` / `triggerName`                                                       | Behavior                                                                                                                                                                                                           |
| --------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Webhook               | `@activepieces/piece-webhook` / `catch_webhook`                                   | You get a `webhook_url` to call from external systems. The payload arrives wrapped: reference fields as `{{trigger['body']['field']}}`. Tested synchronously with your `sample`.                                   |
| Phone call ended      | `@integration-tools/piece-voice` / `phoneCallEnded`                               | Requires `assistant_id`. Attached to the assistant after a green test. Payload fields live directly on the trigger: `{{trigger['extracted_variables']['x']}}`, `{{trigger['customer_phone']}}`, …                  |
| Inbound call          | `@integration-tools/piece-voice` / `inboundCall`                                  | Requires `assistant_id`. Runs before the assistant answers; must end in a respond step returning a flat map of strings.                                                                                            |
| New conversation      | `@integration-tools/piece-voice` / `newConversation`                              | Requires `assistant_id`.                                                                                                                                                                                           |
| Conversation ended    | webhook trigger + `bind_webhook: "conversation_ended"`                            | Requires `assistant_id`. Fires when a chat ends; payload arrives wrapped, so reference fields through `{{trigger['body']['...']}}`.                                                                                |
| Schedule              | `@activepieces/piece-schedule` / `every_x_minutes`, `every_day`, …                | Cannot be fired on demand — activates armed as `active_untested`; the first scheduled run is the proof (check [runs](/api-reference/automations/list-automation-runs)).                                            |
| External integrations | the integration's own trigger (new spreadsheet row, new CRM contact, new lead, …) | Your connected account is attached automatically; if it is missing or expired you get a `needs_connection` / `needs_reconnection` error with the exact steps to fix it in the app. Activates as `active_untested`. |

Steps reference earlier output by step name — `{{step_1['body']['field']}}` for HTTP steps (their JSON nests under `body`). Common step shapes: HTTP requests, code transforms, branches, delays, respond steps, and platform actions (send SMS/WhatsApp, start a call, re-queue a lead). The easiest way to learn a step's exact shape is to read an existing automation with [Get automation](/api-reference/automations/get-automation) or apply a template and inspect what it built.

### Request body

<ParamField type="string">
  A short human name for the automation (max 255 characters)
</ParamField>

<ParamField type="object">
  The automation definition — `{"trigger": {...}, "steps": [...]}` as described above. Max 1 MB.
</ParamField>

<ParamField type="object">
  A realistically-shaped sample payload for the test run (what the trigger will receive). For assistant events, a canonical sample built from the assistant's own variables is used when omitted. Max 256 KB.
</ParamField>

<ParamField type="integer">
  Required for assistant-event automations (`phoneCallEnded`, `inboundCall`, `newConversation`, and `bind_webhook`): the assistant this automation attaches to. It starts receiving that assistant's real events after the test passes. (For the platform triggers, selecting the assistant inside the trigger's `settings.input.assistant` also works — the explicit parameter wins.)
</ParamField>

<ParamField type="string">
  For a webhook-triggered definition only: attach it to the assistant's conversation-ended event. The only supported value is `conversation_ended`. Requires `assistant_id`.
</ParamField>

<ParamField type="boolean">
  Required (`true`) when the definition contains steps that send messages or emails, start calls, or make non-GET HTTP requests — the test run executes them for real.
</ParamField>

### Response

Returns `201` when the automation is active (`active` / `active_untested`), `200` when it was built but its test run failed (`test_failed`), and `422` for a definition that never reached the test run (see error codes below).

<ResponseField name="automation_id" type="string">
  The ID of the created automation
</ResponseField>

<ResponseField name="webhook_url" type="string | null">
  For webhook-triggered automations (including conversation-ended ones): the URL external systems call to fire it. `null` for assistant-event and schedule automations.
</ResponseField>

<ResponseField name="status" type="string">
  * `active` — the test run passed; the automation is live (and attached, for assistant events).
  * `active_untested` — the trigger cannot be fired on demand (schedules, external integrations); the automation is live and armed, and the first real event is the proof.
  * `test_failed` — the test run failed; the automation was left disabled. Read `test.steps` for the per-step classification.
</ResponseField>

<ResponseField name="test" type="object">
  The test run result

  <Expandable title="test properties">
    <ResponseField name="run_status" type="string">
      `SUCCEEDED`, `PAUSED`, `FAILED`, or `not_tested` (untestable triggers); rarely `no_run` when the test produced no execution record. **`PAUSED` counts as success**: the run is parked at a Delay step waiting for its target time — every step before the delay already ran.
    </ResponseField>

    <ResponseField name="steps" type="array">
      Per-step outcome of the test run

      <Expandable title="step properties">
        <ResponseField name="name" type="string">
          The step name (`trigger`, `step_1`, …)
        </ResponseField>

        <ResponseField name="status" type="string">
          `SUCCEEDED`, `FAILED` or `PAUSED`
        </ResponseField>

        <ResponseField name="classification" type="string">
          `ok`, `paused_at_delay`, or — for failures — `wiring_error` (the definition is wrong: fix it and repair via [Update automation](/api-reference/automations/update-automation)), `missing_connection` (an account must be connected in the app first), `missing_record` (the sample referenced data that does not exist — often fine).
        </ResponseField>

        <ResponseField name="error" type="string | null">
          The step's error message, when it failed
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="response" type="object | string | null">
  For synchronously-tested automations (webhook and inbound triggers): what the automation responded during the test run
</ResponseField>

<ResponseField name="binding" type="object | null">
  For assistant-event automations: `{"type": "post_call" | "inbound" | "conversation" | "conversation_ended", "assistant_id": <id>, "bound": <bool>}`. `bound` is `true` only after a green test.
</ResponseField>

### Error codes (`422`)

Hard failures return `{"message": "...", "error": "<code>"}` and nothing is activated. Notable codes:

| `error`                                              | Meaning                                                                                                                                                                              |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `side_effects_require_confirmation`                  | The definition contains steps that would really send during the test — retry with `confirm_side_effects: true` after checking the recipients.                                        |
| `no_steps`                                           | The trigger has no steps chained to it.                                                                                                                                              |
| `invalid_definition` / `unsupported_trigger`         | The definition is missing its trigger, or uses a trigger type that is not supported.                                                                                                 |
| `assistant_required` / `assistant_not_found`         | The trigger needs an `assistant_id`, or the assistant does not belong to your account.                                                                                               |
| `binding_conflict`                                   | The assistant already has an automation (or a custom webhook) for this event — an assistant has one slot per event type. Update the existing automation instead, or delete it first. |
| `needs_connection` / `needs_reconnection`            | The trigger's integration account must be connected (or reconnected) in the app first — the message contains the exact steps.                                                        |
| `import_failed` / `publish_failed` / `create_failed` | The definition was rejected or could not be activated.                                                                                                                               |

<ResponseExample>
  ```json 201 Response (webhook, test passed) theme={null}
  {
    "automation_id": "f4EaLhOW2zoEsXXSOJP2r",
    "webhook_url": "https://automate.autocalls.ai/api/v1/webhooks/f4EaLhOW2zoEsXXSOJP2r",
    "status": "active",
    "test": {
      "run_status": "SUCCEEDED",
      "steps": [
        { "name": "trigger", "status": "SUCCEEDED", "classification": "ok", "error": null },
        { "name": "step_1", "status": "SUCCEEDED", "classification": "ok", "error": null }
      ]
    },
    "response": { "ok": "true", "echo": "hello" },
    "binding": null
  }
  ```

  ```json 201 Response (schedule, activates untested) theme={null}
  {
    "automation_id": "aB3xYz01MnOpQrStUvWxY",
    "webhook_url": null,
    "status": "active_untested",
    "test": {
      "run_status": "not_tested",
      "steps": []
    },
    "response": null,
    "binding": null
  }
  ```

  ```json 422 Response (side effects not confirmed) theme={null}
  {
    "message": "This automation contains steps that would REALLY send messages, emails or start calls during the test run: Send SMS. Confirm with the user first — point those steps at a safe recipient the user owns — then retry with confirm_side_effects set to true.",
    "error": "side_effects_require_confirmation"
  }
  ```
</ResponseExample>


# Delete automation
Source: https://docs.autocalls.ai/api-reference/automations/delete-automation

DELETE /user/automate/flows/{id}
Permanently delete an automation

This endpoint permanently deletes an automation. This cannot be undone — everything the automation did stops, and its definition is unrecoverable. If any of your assistants were attached to it, that attachment is cleared automatically so nothing keeps firing a deleted automation. If you are deleting an automation to replace it and still want any of its current behavior, read it first with [Get automation](/api-reference/automations/get-automation) and carry those steps into the replacement.

### Path Parameters

<ParamField type="string">
  The ID of the automation (from [List automations](/api-reference/automations/list-automations))
</ParamField>

### Response

<ResponseField name="message" type="string">
  `Automation deleted successfully`
</ResponseField>

A missing automation — or one that does not belong to your account — returns a `404` with `{"message": "Automation not found"}`.

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "message": "Automation deleted successfully"
  }
  ```

  ```json 404 Response theme={null}
  {
    "message": "Automation not found"
  }
  ```
</ResponseExample>


# Get automation
Source: https://docs.autocalls.ai/api-reference/automations/get-automation

GET /user/automate/flows/{id}
Get a single automation, including its full definition

This endpoint returns a single automation you own, including its full definition (the trigger and its chained steps) so you can inspect or repair it.

### Path Parameters

<ParamField type="string">
  The ID of the automation (from [List automations](/api-reference/automations/list-automations))
</ParamField>

### Query Parameters

<ParamField type="boolean">
  By default, credential-bearing values inside the definition (API keys, tokens, `Authorization` headers) are masked as `••• hidden`. Pass `true` to return them unmasked.
</ParamField>

### Response

<ResponseField name="data" type="object">
  The automation

  <Expandable title="data properties">
    <ResponseField name="id" type="string">
      The unique ID of the automation
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the automation
    </ResponseField>

    <ResponseField name="status" type="string">
      `enabled` or `disabled`
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the automation was last updated
    </ResponseField>

    <ResponseField name="definition" type="object">
      The automation's definition: the trigger object with its steps chained under `nextAction`. This is the artifact you edit and send back through [Update automation](/api-reference/automations/update-automation) to repair or extend the automation. See [Create automation](/api-reference/automations/create-automation) for the definition format.
    </ResponseField>

    <ResponseField name="binding" type="object | null">
      When the automation is attached to an assistant event: `{type, assistant_id, assistant_name}` (see [List automations](/api-reference/automations/list-automations)). Otherwise `null`.
    </ResponseField>
  </Expandable>
</ResponseField>

A missing automation — or one that does not belong to your account — returns a `404` with `{"message": "Automation not found"}`.

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": {
      "id": "f4EaLhOW2zoEsXXSOJP2r",
      "name": "Order lookup",
      "status": "enabled",
      "updated_at": "2026-07-24T18:23:57.259Z",
      "definition": {
        "name": "trigger",
        "type": "PIECE_TRIGGER",
        "displayName": "Catch Webhook",
        "settings": {
          "pieceName": "@activepieces/piece-webhook",
          "triggerName": "catch_webhook"
        },
        "nextAction": {
          "name": "step_1",
          "type": "PIECE",
          "displayName": "Look up the order",
          "settings": {
            "pieceName": "@activepieces/piece-http",
            "actionName": "send_request",
            "input": {
              "url": "https://api.example.com/orders",
              "method": "GET",
              "headers": {
                "Authorization": "••• hidden"
              }
            }
          }
        }
      },
      "binding": null
    }
  }
  ```

  ```json 404 Response theme={null}
  {
    "message": "Automation not found"
  }
  ```
</ResponseExample>


# List automation runs
Source: https://docs.autocalls.ai/api-reference/automations/list-automation-runs

GET /user/automate/flows/{id}/runs
List an automation's recent executions, or one execution's step-by-step detail

This endpoint lists an automation's recent executions (newest first). Pass `run_id` to get one execution's step-by-step detail with a per-step classification — this is your debugger when an automation is failing.

Once you have fixed what made a run fail, retry it from its failed step with [Retry automation run](/api-reference/automations/retry-automation-run) — take the run's id from this list.

### Path Parameters

<ParamField type="string">
  The ID of the automation (from [List automations](/api-reference/automations/list-automations))
</ParamField>

### Query Parameters

<ParamField type="string">
  A run ID from the list — returns that run's step-by-step detail instead of the list
</ParamField>

<ParamField type="integer">
  How many recent runs to list (1–20, default 10)
</ParamField>

### Response — list (no `run_id`)

<ResponseField name="runs" type="array">
  The automation's recent executions, newest first

  <Expandable title="run properties">
    <ResponseField name="id" type="string">
      The run ID — pass it back as `run_id` for the step-by-step detail, or to [Retry automation run](/api-reference/automations/retry-automation-run) for a failed run
    </ResponseField>

    <ResponseField name="status" type="string">
      `SUCCEEDED`, `FAILED`, `PAUSED` (parked at a Delay step waiting for its target time — not a failure) or `RUNNING`
    </ResponseField>

    <ResponseField name="start_time" type="string">
      When the run started
    </ResponseField>

    <ResponseField name="duration_ms" type="integer">
      The run's duration in milliseconds
    </ResponseField>
  </Expandable>
</ResponseField>

### Response — detail (with `run_id`)

<ResponseField name="run" type="object">
  The execution's detail

  <Expandable title="run properties">
    <ResponseField name="id" type="string">
      The run ID
    </ResponseField>

    <ResponseField name="status" type="string">
      `SUCCEEDED`, `FAILED`, `PAUSED` or `RUNNING`
    </ResponseField>

    <ResponseField name="start_time" type="string">
      When the run started
    </ResponseField>

    <ResponseField name="duration_ms" type="integer">
      The run's duration in milliseconds
    </ResponseField>

    <ResponseField name="steps" type="array">
      Per-step outcome — same shape as the `test.steps` of [Create automation](/api-reference/automations/create-automation): `{name, status, classification, error}`, where `classification` is `ok`, `paused_at_delay`, `wiring_error`, `missing_connection` or `missing_record`
    </ResponseField>
  </Expandable>
</ResponseField>

A missing automation — or one that does not belong to your account — returns a `404` with `{"message": "Automation not found"}`. A `run_id` that does not belong to this automation returns a `404` with `{"message": "Run not found for this automation"}`.

<ResponseExample>
  ```json 200 Response (list) theme={null}
  {
    "runs": [
      {
        "id": "yHhXbqWj3zJZ5ztDNfUry",
        "status": "SUCCEEDED",
        "start_time": "2026-07-24T18:23:59.634Z",
        "duration_ms": 1
      },
      {
        "id": "x2PqLm90AbCdEfGhIjKlM",
        "status": "FAILED",
        "start_time": "2026-07-24T17:10:12.000Z",
        "duration_ms": 410
      }
    ]
  }
  ```

  ```json 200 Response (detail) theme={null}
  {
    "run": {
      "id": "x2PqLm90AbCdEfGhIjKlM",
      "status": "FAILED",
      "start_time": "2026-07-24T17:10:12.000Z",
      "duration_ms": 410,
      "steps": [
        { "name": "trigger", "status": "SUCCEEDED", "classification": "ok", "error": null },
        {
          "name": "step_1",
          "status": "FAILED",
          "classification": "missing_connection",
          "error": "Request failed with status code 401"
        }
      ]
    }
  }
  ```

  ```json 404 Response theme={null}
  {
    "message": "Run not found for this automation"
  }
  ```
</ResponseExample>


# List automation templates
Source: https://docs.autocalls.ai/api-reference/automations/list-automation-templates

GET /user/automate/templates
List the ready-made automation templates and the parameters each one needs

This endpoint lists the curated automation templates: ready-made automations you apply with [Apply automation template](/api-reference/automations/apply-automation-template) by supplying a few parameters, instead of writing a definition from scratch. Each entry describes its parameters, the account connections it needs, whether it attaches to an assistant, and whether it sends real messages during its test run.

### Available templates

| Key                                | What it does                                                | Assistant | Sends for real | Connections      | Params (\* = required)                                                                                      |
| ---------------------------------- | ----------------------------------------------------------- | --------- | -------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `post-call-qualified-to-sheets`    | Save qualified leads to Google Sheets after each call       | yes       | no             | `google-sheets`  | `spreadsheet_id`\*, `qualified_variable`                                                                    |
| `post-call-transcript-email`       | Email the call transcript after each call                   | yes       | yes            | `gmail`          | `recipient_email`\*                                                                                         |
| `post-call-hot-lead-alert`         | Hot lead email alert after each call                        | yes       | yes            | `gmail`          | `alert_email`\*, `hot_variable`                                                                             |
| `post-call-sms-followup`           | SMS follow-up after each call                               | yes       | yes            | —                | `from_phone_id`\*, `message`\*                                                                              |
| `post-call-whatsapp-confirmation`  | WhatsApp confirmation after each call                       | yes       | yes            | —                | `sender_id`\*, `whatsapp_template`\*, `variable_1`                                                          |
| `post-call-crm-note-http`          | Log every call to your CRM / any API                        | yes       | yes            | —                | `endpoint_url`\*, `auth_header`, `auth_value`                                                               |
| `post-call-callback`               | Call the customer back at the time they asked for           | yes       | yes            | —                | `callback_variable`, `time_variable`, `from_timezone`                                                       |
| `inbound-caller-lookup-http`       | Recognize inbound callers via your API                      | yes       | no             | —                | `lookup_url`\*, `api_key_header`, `api_key`, `phone_format`                                                 |
| `conversation-ended-summary-email` | Email a summary when a chat ends                            | yes       | yes            | `gmail`          | `recipient_email`\*                                                                                         |
| `lead-intake-webhook`              | New lead from any system, call them automatically           | no        | yes            | —                | `campaign_id`\*                                                                                             |
| `midcall-http-lookup`              | Mid-call lookup in an external API                          | no        | no             | —                | `lookup_url`\*, `auth_header_value`                                                                         |
| `sheet-rows-to-campaign`           | Call the leads added to a Google Sheet                      | no        | yes            | `google-sheets`  | `spreadsheet_id`\*, `campaign_id`\*, `phone_column`, `name_column`, `minutes`                               |
| `sheet-rows-to-whatsapp-daily`     | Daily WhatsApp template to leads from a Google Sheet        | no        | yes            | `google-sheets`  | `spreadsheet_id`\*, `sender_id`\*, `whatsapp_template`\*, `phone_column`, `name_column`, `hour`, `timezone` |
| `calcom-call-before-appointment`   | Call the customer before their Cal.com appointment          | no        | yes            | `cal-com`        | `assistant_id`\*, `hours_before`, `phone_expression`                                                        |
| `calcom-cancel-reschedule-midcall` | Cancel or reschedule Cal.com appointments during a call     | no        | yes            | —                | `attendee_email`\*                                                                                          |
| `ghl-appointment-manage-midcall`   | Cancel or reschedule GoHighLevel appointments during a call | no        | no             | `lead-connector` | `timezone`                                                                                                  |

Required connections are one-time account links (Google Sheets, Gmail, Cal.com, …) made in the app on the Automate page, under Connections.

### Response

<ResponseField name="data" type="array">
  The template library

  <Expandable title="template properties">
    <ResponseField name="key" type="string">
      The template key — pass it in the URL of [Apply automation template](/api-reference/automations/apply-automation-template)
    </ResponseField>

    <ResponseField name="name" type="string">
      The template's name (also the default name of the automation it creates)
    </ResponseField>

    <ResponseField name="description" type="string">
      What the resulting automation does
    </ResponseField>

    <ResponseField name="use_when" type="string">
      When this template is the right choice
    </ResponseField>

    <ResponseField name="binding" type="string | null">
      The assistant event the resulting automation attaches to (`post_call`, `inbound`, `conversation_ended`), or `null` for templates that do not attach to an assistant event
    </ResponseField>

    <ResponseField name="requires_assistant" type="boolean">
      Whether `assistant_id` is required when applying it
    </ResponseField>

    <ResponseField name="required_connections" type="array">
      Account connections that must exist before applying (e.g. `google-sheets`, `gmail`)
    </ResponseField>

    <ResponseField name="side_effects" type="boolean">
      Whether the resulting automation really sends messages / starts calls — applying it requires `confirm_side_effects: true`
    </ResponseField>

    <ResponseField name="params" type="array">
      The parameters the template needs

      <Expandable title="param properties">
        <ResponseField name="key" type="string">
          The parameter key to send in `params` when applying
        </ResponseField>

        <ResponseField name="label" type="string">
          Human-readable label
        </ResponseField>

        <ResponseField name="description" type="string">
          What the value is and where to find it
        </ResponseField>

        <ResponseField name="required" type="boolean">
          Whether the parameter must be supplied
        </ResponseField>

        <ResponseField name="default" type="string">
          The value used when the parameter is omitted (optional parameters only)
        </ResponseField>

        <ResponseField name="example" type="string">
          An example value — for illustration only, never apply a template with example values
        </ResponseField>

        <ResponseField name="auto" type="string">
          Present on some optional parameters: how the value is filled automatically when omitted (e.g. `assistant_timezone` — the supplied assistant's own timezone)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="test_sample" type="object">
      Present on some templates: the sample payload their test run uses
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response (truncated) theme={null}
  {
    "data": [
      {
        "key": "post-call-qualified-to-sheets",
        "name": "Save qualified leads to Google Sheets",
        "description": "After each call, if the AI marked the caller as qualified, appends a row (phone, name, summary, status) to your Google Sheet.",
        "use_when": "The user wants qualified calls or call outcomes collected in a spreadsheet automatically.",
        "binding": "post_call",
        "requires_assistant": true,
        "required_connections": ["google-sheets"],
        "side_effects": false,
        "params": [
          {
            "key": "spreadsheet_id",
            "label": "Google Spreadsheet ID",
            "description": "The spreadsheet to append rows to.",
            "required": true,
            "example": "1AbCdEfGhIjKlMnOpQrStUvWxYz"
          },
          {
            "key": "qualified_variable",
            "label": "Qualified variable name",
            "description": "The post-call variable checked for true before saving (the assistant must extract it).",
            "required": false,
            "default": "status",
            "example": "qualified"
          }
        ]
      }
    ]
  }
  ```
</ResponseExample>


# List automations
Source: https://docs.autocalls.ai/api-reference/automations/list-automations

GET /user/automate/flows
List the automations in your account

This endpoint lists every automation in your account, with its current status and — for automations attached to an assistant event — the assistant it is attached to.

### Response

<ResponseField name="data" type="array">
  The list of automations

  <Expandable title="data item properties">
    <ResponseField name="id" type="string">
      The unique ID of the automation. Use it with the other automation endpoints.
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the automation
    </ResponseField>

    <ResponseField name="status" type="string">
      `enabled` (live, reacting to events) or `disabled` (off — a failed test run or an explicit disable)
    </ResponseField>

    <ResponseField name="binding" type="object | null">
      Present when the automation is attached to one of your assistants' events, otherwise `null`

      <Expandable title="binding properties">
        <ResponseField name="type" type="string">
          The assistant event this automation reacts to: `post_call`, `inbound`, `conversation` or `conversation_ended`
        </ResponseField>

        <ResponseField name="assistant_id" type="integer">
          The ID of the assistant it is attached to
        </ResponseField>

        <ResponseField name="assistant_name" type="string">
          The name of the assistant it is attached to
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": [
      {
        "id": "OaeThAHzIjAPTmMJAhgwm",
        "name": "Qualified leads to Google Sheets",
        "status": "enabled",
        "binding": {
          "type": "post_call",
          "assistant_id": 123,
          "assistant_name": "Sales Assistant"
        }
      },
      {
        "id": "nCazgFt1COAmGVgCWkvxY",
        "name": "Daily call report (17:00)",
        "status": "disabled",
        "binding": null
      }
    ]
  }
  ```
</ResponseExample>


# Restore previous version
Source: https://docs.autocalls.ai/api-reference/automations/restore-automation

POST /user/automate/flows/{id}/restore
Roll an automation back to its previous published version

This endpoint rolls an automation back to the version published immediately before the current one and re-publishes it — the undo for an update that made things worse. Only the previous version is supported. An automation that was turned off stays off after the restore.

### Path Parameters

<ParamField type="string">
  The ID of the automation (from [List automations](/api-reference/automations/list-automations))
</ParamField>

This endpoint takes no request body.

### Response

<ResponseField name="automation_id" type="string">
  The automation's ID
</ResponseField>

<ResponseField name="name" type="string">
  The automation's name after the restore
</ResponseField>

<ResponseField name="status" type="string">
  `enabled` or `disabled` — the on/off state the automation had going into the restore is preserved
</ResponseField>

<ResponseField name="restored_version_id" type="string">
  The ID of the version that is now live
</ResponseField>

<ResponseField name="note" type="string">
  Confirmation that the previous version was restored and re-published
</ResponseField>

A missing automation — or one that does not belong to your account — returns a `404`.

### Error codes (`422`)

| `error`               | Meaning                                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `no_previous_version` | There is no earlier version of this automation to roll back to.                                                                    |
| `rollback_failed`     | The previous version could not be restored — nothing changed.                                                                      |
| `publish_failed`      | The previous version was restored as the draft but could not be published, so it is not live yet — publish it in the app or retry. |

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "automation_id": "f4EaLhOW2zoEsXXSOJP2r",
    "name": "Order lookup",
    "status": "enabled",
    "restored_version_id": "8auMJQtqBnE1X8ZP7WVnI",
    "note": "Rolled back to the previous published version and re-published it live."
  }
  ```

  ```json 422 Response (nothing to roll back to) theme={null}
  {
    "message": "There is no earlier version of this automation to roll back to.",
    "error": "no_previous_version"
  }
  ```

  ```json 404 Response theme={null}
  {
    "message": "Automation not found, or it does not belong to your account.",
    "error": "not_found"
  }
  ```
</ResponseExample>


# Retry automation run
Source: https://docs.autocalls.ai/api-reference/automations/retry-automation-run

POST /user/automate/flows/{id}/runs/{run_id}/retry
Retry a failed run from its failed step

This endpoint retries a failed execution **from its failed step**: steps that already succeeded are not re-executed, so any side effect they already caused (an email already sent, a row already written) is not repeated. Use it after fixing what made the run fail — a reconnected account, a recovered external API — instead of waiting for the next trigger event. The failed step and everything after it then run for real, completing the original event's work.

Take the run's id from [List automation runs](/api-reference/automations/list-automation-runs). A retry resumes the **same** run — it does not create a new one.

### Path Parameters

<ParamField type="string">
  The ID of the automation (from [List automations](/api-reference/automations/list-automations))
</ParamField>

<ParamField type="string">
  The ID of the failed run (from [List automation runs](/api-reference/automations/list-automation-runs))
</ParamField>

This endpoint takes no request body.

### Response

<ResponseField name="run_id" type="string">
  The retried run's ID (the same run that was passed in)
</ResponseField>

<ResponseField name="status" type="string">
  The run's status right after the retry (e.g. `RUNNING`, or `SUCCEEDED` when it finished instantly)
</ResponseField>

<ResponseField name="note" type="string">
  Confirmation that already-succeeded steps were not re-executed
</ResponseField>

A missing automation or run — or one that does not belong to your account — returns a `404`.

### Error codes (`422`)

| `error`        | Meaning                                                                                                                                                                                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `retry_no_op`  | The retry did not resume the run — its saved state is stale, most commonly because the run passed through a Delay step before failing. Such a run cannot be resumed as-is; the message lists the safe options (repair the automation, or wait for its next real trigger event). |
| `retry_failed` | The retry could not be started — try again shortly.                                                                                                                                                                                                                             |

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "run_id": "yHhXbqWj3zJZ5ztDNfUry",
    "status": "RUNNING",
    "note": "Retried FROM the failed step — steps that already succeeded were NOT re-executed, so their side effects were not repeated."
  }
  ```

  ```json 422 Response (not resumable) theme={null}
  {
    "message": "The retry did not resume this run (its status is still 'FAILED') — its saved state is likely stale, most commonly because the run passed through a Delay step before failing. This run cannot be resumed as-is. To force a fresh full run (re-executes EVERY step, including any that already sent a message/email/call — get the user's explicit confirmation first, then rebuild via update-automation's repair path), or otherwise wait for the automation's next real trigger event.",
    "error": "retry_no_op"
  }
  ```

  ```json 404 Response theme={null}
  {
    "message": "Run not found for this automation.",
    "error": "not_found"
  }
  ```
</ResponseExample>


# Update automation
Source: https://docs.autocalls.ai/api-reference/automations/update-automation

PUT /user/automate/flows/{id}
Rename an automation, turn it on or off, or repair it with a corrected definition

This endpoint has two modes:

* **Rename / toggle** — pass `name` and/or `enabled` to rename the automation or turn it on/off.
* **Repair** — pass a corrected `flow` definition and the automation is rebuilt in place, re-tested with a **real run**, and re-activated only when the test passes. Use this after diagnosing a failure with [Get automation](/api-reference/automations/get-automation) and [List automation runs](/api-reference/automations/list-automation-runs).

To undo a repair that made things worse, roll back to the previous published version with [Restore previous version](/api-reference/automations/restore-automation).

<Warning>
  A repair definition **replaces the whole automation** — it is never merged. Read the current definition first and resend the complete chain, including every step that must stay; steps you leave out are deleted. The repair test run executes the automation for real, so `confirm_side_effects: true` is required again when the corrected definition contains sending steps.
</Warning>

### Path Parameters

<ParamField type="string">
  The ID of the automation (from [List automations](/api-reference/automations/list-automations))
</ParamField>

### Request body

<ParamField type="string">
  A new name for the automation (max 255 characters). In repair mode, the current name is kept when omitted.
</ParamField>

<ParamField type="boolean">
  `true` to turn the automation on, `false` to turn it off
</ParamField>

<ParamField type="object">
  Repair mode: the corrected full definition, in the same format as [Create automation](/api-reference/automations/create-automation) (`{"trigger": {...}, "steps": [...]}`). Max 1 MB.
</ParamField>

<ParamField type="object">
  Sample payload for the repair test run (for assistant events, the canonical sample is used when omitted). Max 256 KB.
</ParamField>

<ParamField type="integer">
  For repairs of assistant-event automations: the assistant to (re)attach to. Usually already carried inside the definition's trigger.
</ParamField>

<ParamField type="boolean">
  Required (`true`) when the corrected definition contains steps that send messages or emails, start calls, or make non-GET HTTP requests
</ParamField>

A request with none of `name`, `enabled` or `flow` returns a `422` asking for at least one of them.

### Response — rename / toggle

<ResponseField name="data" type="object">
  The refreshed automation summary

  <Expandable title="data properties">
    <ResponseField name="id" type="string">
      The automation ID
    </ResponseField>

    <ResponseField name="name" type="string">
      The automation's (possibly new) name
    </ResponseField>

    <ResponseField name="status" type="string">
      `enabled` or `disabled`
    </ResponseField>

    <ResponseField name="updated" type="boolean">
      Whether every requested change was applied
    </ResponseField>
  </Expandable>
</ResponseField>

### Response — repair

The same envelope as [Create automation](/api-reference/automations/create-automation) (`automation_id`, `status`, `test`, `response`, `binding`), without `webhook_url` — a repaired automation keeps its original webhook URL. Returned with HTTP `200`; `status` is `active`, `active_untested` or `test_failed`. A repair whose test fails leaves the automation disabled; a repair rejected before the test run (e.g. `no_steps`) leaves the existing automation untouched.

A missing automation — or one that does not belong to your account — returns a `404` with `{"message": "Automation not found"}`.

<ResponseExample>
  ```json 200 Response (rename + disable) theme={null}
  {
    "data": {
      "id": "f4EaLhOW2zoEsXXSOJP2r",
      "name": "Order lookup v2",
      "status": "disabled",
      "updated": true
    }
  }
  ```

  ```json 200 Response (repair, test passed) theme={null}
  {
    "automation_id": "f4EaLhOW2zoEsXXSOJP2r",
    "status": "active",
    "test": {
      "run_status": "SUCCEEDED",
      "steps": []
    },
    "response": null,
    "binding": null
  }
  ```

  ```json 404 Response theme={null}
  {
    "message": "Automation not found"
  }
  ```
</ResponseExample>


# Delete call
Source: https://docs.autocalls.ai/api-reference/calls/delete-call

DELETE /user/calls/{call}
Delete a specific call record

This endpoint allows you to delete a specific call record that belongs to the authenticated user.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the call to delete
</ParamField>

### Response

<ResponseField name="message" type="string">
  Confirmation message indicating the call was deleted successfully
</ResponseField>

### Error Responses

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message when the call is not found or doesn't belong to the authenticated user
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "message": "Call deleted successfully"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Call not found"
  }
  ```
</ResponseExample>

### Notes

* Only calls that belong to assistants owned by the authenticated user can be deleted
* Once a call is deleted, it cannot be recovered
* This action will permanently remove the call record, including any associated transcript, recording, and metadata
* The call recording file (if exists) will also be deleted from storage


# Get call
Source: https://docs.autocalls.ai/api-reference/calls/get-call

GET /user/calls/{id}
Retrieve details of a specific call by ID

This endpoint allows you to retrieve detailed information about a specific call belonging to the authenticated user.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the call
</ParamField>

### Response fields

<ResponseField name="id" type="integer">
  The unique identifier of the call
</ResponseField>

<ResponseField name="assistant_name" type="string">
  The name of the assistant that handled the call
</ResponseField>

<ResponseField name="campaign_name" type="string">
  The name of the campaign this call belongs to (if applicable)
</ResponseField>

<ResponseField name="type" type="string">
  The type of the call (`inbound`, `outbound`, or `web`)
</ResponseField>

<ResponseField name="duration" type="integer">
  The duration of the call in seconds
</ResponseField>

<ResponseField name="assistant_phone_number" type="string">
  The phone number used by the assistant
</ResponseField>

<ResponseField name="client_phone_number" type="string">
  The phone number of the client
</ResponseField>

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

<ResponseField name="transcript" type="string">
  The transcript of the call conversation
</ResponseField>

<ResponseField name="variables" type="object">
  Variables collected during the call
</ResponseField>

<ResponseField name="evaluation" type="object">
  Evaluation data for the call performance
</ResponseField>

<ResponseField name="webhook_response" type="object">
  HTTP response from the assistant's post-call webhook (`status`, `body`). Bodies larger than 8 KB are stored truncated, with `truncated` and `body_bytes` set.
</ResponseField>

<ResponseField name="carrier_cost" type="number">
  The cost charged by the carrier for this call
</ResponseField>

<ResponseField name="total_cost" type="number">
  The total cost of the call including all fees
</ResponseField>

<ResponseField name="answered_by" type="string">
  Who answered the call (`human`, `machine`, or `unknown`)
</ResponseField>

<ResponseField name="recording_url" type="string">
  URL to the call recording (if available and enabled)
</ResponseField>

<ResponseField name="created_at" type="string">
  The date and time when the call was created
</ResponseField>

<ResponseField name="updated_at" type="string">
  The date and time when the call was last updated
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "id": 123,
    "assistant_name": "Sales Assistant",
    "campaign_name": "Q4 Outreach Campaign",
    "type": "outbound",
    "duration": 245,
    "assistant_phone_number": "+1234567890",
    "client_phone_number": "+1987654321",
    "status": "completed",
    "transcript": "Hello, this is Sarah from Autocalls. How are you doing today?...",
    "variables": {
      "customer_name": "John Smith",
      "interest_level": "high",
      "follow_up_date": "2025-08-15"
    },
    "evaluation": {
      "sentiment": "positive",
      "outcome": "qualified_lead",
      "score": 8.5
    },
    "webhook_response": {
      "status": "success",
      "data": {
        "crm_contact_id": "abc123"
      }
    },
    "carrier_cost": 0.02,
    "total_cost": 0.025,
    "answered_by": "human",
    "recording_url": "https://recordings.autocalls.ai/calls/123.mp3",
    "created_at": "2025-08-04 14:30:00",
    "updated_at": "2025-08-04 14:34:05"
  }
  ```

  ```json 404 Response theme={null}
  {
    "message": "Call not found"
  }
  ```
</ResponseExample>


# List calls
Source: https://docs.autocalls.ai/api-reference/calls/get-calls

GET /user/calls
List all calls for the authenticated user with filtering options

This endpoint allows you to list all calls belonging to the authenticated user with various filtering options.

Post-call webhook HTTP responses are not included here. Use [Get call](/api-reference/calls/get-call) for `webhook_response`.

### Query Parameters

<ParamField type="string">
  Filter calls by status. Possible values: `initiated`, `ringing`, `busy`, `in-progress`, `ended`, `completed`, `ended_by_customer`, `ended_by_assistant`, `no-answer`, `failed`
</ParamField>

<ParamField type="string">
  Filter calls by type. Possible values: `inbound`, `outbound`, `web`
</ParamField>

<ParamField type="string">
  Filter calls by client phone number
</ParamField>

<ParamField type="integer">
  Filter calls by assistant ID
</ParamField>

<ParamField type="integer">
  Filter calls by campaign ID
</ParamField>

<ParamField type="string">
  Filter calls from this date (YYYY-MM-DD format)
</ParamField>

<ParamField type="string">
  Filter calls until this date (YYYY-MM-DD format)
</ParamField>

<ParamField type="integer">
  Number of calls per page (1-100, default: 15)
</ParamField>

<ParamField type="integer">
  Page number (default: 1)
</ParamField>

### Response fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the call
    </ResponseField>

    <ResponseField name="assistant_name" type="string">
      The name of the assistant that handled the call
    </ResponseField>

    <ResponseField name="campaign_name" type="string">
      The name of the campaign this call belongs to (if applicable)
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the call (`inbound`, `outbound`, or `web`)
    </ResponseField>

    <ResponseField name="duration" type="integer">
      The duration of the call in seconds
    </ResponseField>

    <ResponseField name="assistant_phone_number" type="string">
      The phone number used by the assistant
    </ResponseField>

    <ResponseField name="client_phone_number" type="string">
      The phone number of the client
    </ResponseField>

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

    <ResponseField name="transcript" type="string">
      The transcript of the call conversation
    </ResponseField>

    <ResponseField name="variables" type="object">
      Variables collected during the call
    </ResponseField>

    <ResponseField name="evaluation" type="object">
      Evaluation data for the call performance
    </ResponseField>

    <ResponseField name="carrier_cost" type="number">
      The cost charged by the carrier for this call
    </ResponseField>

    <ResponseField name="total_cost" type="number">
      The total cost of the call including all fees
    </ResponseField>

    <ResponseField name="answered_by" type="string">
      Who answered the call (`human`, `machine`, or `unknown`)
    </ResponseField>

    <ResponseField name="recording_url" type="string">
      URL to the call recording (if available and enabled)
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The date and time when the call was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      The date and time when the call was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="current_page" type="integer">
  The current page number
</ResponseField>

<ResponseField name="per_page" type="integer">
  Number of items per page
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of calls matching the criteria
</ResponseField>

<ResponseField name="last_page" type="integer">
  The last page number
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 123,
        "assistant_name": "Sales Assistant",
        "campaign_name": "Q4 Outreach Campaign",
        "type": "outbound",
        "duration": 245,
        "assistant_phone_number": "+1234567890",
        "client_phone_number": "+1987654321",
        "status": "completed",
        "transcript": "Hello, this is Sarah from Autocalls. How are you doing today?...",
        "variables": {
          "customer_name": "John Smith",
          "interest_level": "high",
          "follow_up_date": "2025-08-15"
        },
        "evaluation": {
          "sentiment": "positive",
          "outcome": "qualified_lead",
          "score": 8.5
        },
        "carrier_cost": 0.02,
        "total_cost": 0.025,
        "answered_by": "human",
        "recording_url": "https://recordings.autocalls.ai/calls/123.mp3",
        "created_at": "2025-08-04 14:30:00",
        "updated_at": "2025-08-04 14:34:05"
      }
    ],
    "first_page_url": "https://app.autocalls.ai/api/user/calls?page=1",
    "from": 1,
    "last_page": 10,
    "last_page_url": "https://app.autocalls.ai/api/user/calls?page=10",
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://app.autocalls.ai/api/user/calls?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://app.autocalls.ai/api/user/calls?page=2",
        "label": "2",
        "active": false
      }
    ],
    "next_page_url": "https://app.autocalls.ai/api/user/calls?page=2",
    "path": "https://app.autocalls.ai/api/user/calls",
    "per_page": 15,
    "prev_page_url": null,
    "to": 15,
    "total": 150
  }
  ```
</ResponseExample>


# Make a phone call
Source: https://docs.autocalls.ai/api-reference/calls/make-phone-call

POST /user/make_call
Make a phone call

This endpoint allows you to make a phone call.

### Request body

<ParamField type="string">
  The phone number of the customer in E.164 format (e.g. +1234567890)
</ParamField>

<ParamField type="integer">
  The ID of the assistant to make the call with
</ParamField>

<ParamField type="object">
  Custom variables to pass to the call. You can include **any variables that are defined on your assistant** (see [Call variables](/ai-assistants/settings/prompt-and-tools#call-variables)). The examples below are just for illustration — use your own variable names as configured in the assistant settings.

  <Expandable title="Example variables (add your own)">
    <ParamField type="string">
      e.g. the name of the customer
    </ParamField>

    <ParamField type="string">
      e.g. the email of the customer
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="message" type="string">
  The message of the response
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "message": "Call initiated successfully",
    "data": {}
  }
  ```
</ResponseExample>


# Create campaign
Source: https://docs.autocalls.ai/api-reference/campaigns/create-campaign

POST /user/campaign
Create a draft call, WhatsApp, or SMS campaign

Create a new campaign. Campaigns start in `draft` — add leads, then start with [Update campaign status](/api-reference/campaigns/update-status).

Supported channels:

* **`call`** (default) — outbound voice with an OUTBOUND assistant
* **`whatsapp`** — approved WhatsApp template via one of your senders
* **`sms`** — SMS body from an SMS-capable number (may be temporarily unavailable on the platform)

### Request body

#### Shared

<ParamField type="string">
  Campaign name. Maximum 255 characters.
</ParamField>

<ParamField type="string">
  `call`, `whatsapp`, or `sms`.
</ParamField>

<ParamField type="string">
  IANA timezone for the send/call window (e.g. `America/New_York`). Defaults to the assistant timezone for call campaigns, otherwise your account timezone.
</ParamField>

<ParamField type="array">
  Preferred schedule: one or more daily windows as objects with `start` and `end` in `HH:MM`. Overnight windows are supported when `end` is earlier than `start` (e.g. `16:00` → `02:00`).
</ParamField>

<ParamField type="string">
  Legacy single-window start (`HH:MM`). Used if `schedule_windows` is omitted.
</ParamField>

<ParamField type="string">
  Legacy single-window end (`HH:MM`). Overnight when end \< start.
</ParamField>

<ParamField type="string">
  Optional ISO datetime. When set, the campaign can be scheduled to auto-start at that time.
</ParamField>

<ParamField type="array">
  Weekdays: `monday` … `sunday`.
</ParamField>

<ParamField type="integer">
  Max retry attempts per lead. Range: 1–5.
</ParamField>

<ParamField type="integer">
  Minutes between retries. Range: 10–4320.
</ParamField>

<ParamField type="boolean">
  Automatically mark the campaign complete when no remaining work is left.
</ParamField>

#### Call campaigns

<ParamField type="integer">
  Required for `channel=call`. Must be an OUTBOUND assistant you own.
</ParamField>

<ParamField type="integer">
  Concurrent calls (plan-bounded, max 10).
</ParamField>

<ParamField type="array">
  Outbound from-number IDs available to your account.
</ParamField>

<ParamField type="boolean">
  Retry when a call hits voicemail.
</ParamField>

<ParamField type="boolean">
  Keep retrying until a boolean post-call goal variable is true.
</ParamField>

<ParamField type="string">
  Boolean post-call schema variable name used with `retry_on_goal_incomplete`.
</ParamField>

<ParamField type="string">
  Optional call→text follow-up after max call retries: `whatsapp` or `sms`.
</ParamField>

<ParamField type="integer">
  Required when `fallback_channel=whatsapp`.
</ParamField>

<ParamField type="integer">
  Required when `fallback_channel=whatsapp`. Must be an approved template on that sender.
</ParamField>

<ParamField type="integer">
  Required when `fallback_channel=sms`.
</ParamField>

<ParamField type="string">
  Required when `fallback_channel=sms`. Supports `{{variable}}` placeholders.
</ParamField>

<ParamField type="object">
  Maps WhatsApp template placeholders (e.g. `"1"`) to lead variable keys for the fallback send.
</ParamField>

#### WhatsApp campaigns

<ParamField type="integer">
  Required for `channel=whatsapp`. Sender you own.
</ParamField>

<ParamField type="integer">
  Required for `channel=whatsapp`. Approved template on that sender.
</ParamField>

<ParamField type="object">
  Maps template placeholders (e.g. `"1"`) to lead variable keys.
</ParamField>

<ParamField type="integer">
  Per-campaign send rate (1–10). WhatsApp campaigns also share a **user-wide pool of 10** in-flight sends across all your active WhatsApp campaigns.
</ParamField>

#### SMS campaigns

<ParamField type="integer">
  Required for `channel=sms`. Must be SMS-capable and available to you.
</ParamField>

<ParamField type="string">
  Required for `channel=sms`. Max 1600 characters. Supports `{{variable}}` placeholders.
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  Created campaign (same shape as [Get campaign](/api-reference/campaigns/get-campaign)), including `channel`, schedule, text config, and fallback fields.
</ResponseField>

### Error responses

<ResponseField name="422 Unprocessable Entity">
  Plan limit, invalid assistant/sender/template, disabled channel, or validation errors.
</ResponseField>

<ResponseExample>
  ```json 201 Created (call) theme={null}
  {
    "message": "Campaign created successfully",
    "data": {
      "id": 1,
      "name": "Product Demo Campaign",
      "channel": "call",
      "status": "draft",
      "assistant_id": 42,
      "timezone": "Europe/Bucharest",
      "max_calls_in_parallel": 3,
      "messages_per_minute": null,
      "schedule_windows": [{ "start": "09:00", "end": "18:00" }],
      "scheduled_start_at": null,
      "allowed_hours_start_time": "09:00",
      "allowed_hours_end_time": "18:00",
      "allowed_days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
      "max_retries": 3,
      "retry_interval": 60,
      "retry_on_voicemail": false,
      "retry_on_goal_incomplete": false,
      "goal_completion_variable": null,
      "mark_complete_when_no_leads": true,
      "phone_number_ids": [11, 12],
      "whatsapp_sender_id": null,
      "whatsapp_template_id": null,
      "sms_from_phone_number_id": null,
      "sms_body": null,
      "text_variable_mapping": null,
      "fallback_channel": "whatsapp",
      "fallback_whatsapp_sender_id": 7,
      "fallback_whatsapp_template_id": 15,
      "fallback_sms_from_phone_number_id": null,
      "fallback_sms_body": null,
      "fallback_variable_mapping": { "1": "customer_name" },
      "created_at": "2026-07-24 18:00:00",
      "updated_at": "2026-07-24 18:00:00"
    }
  }
  ```

  ```json 201 Created (whatsapp) theme={null}
  {
    "message": "Campaign created successfully",
    "data": {
      "id": 2,
      "name": "WhatsApp Follow-up",
      "channel": "whatsapp",
      "status": "draft",
      "assistant_id": null,
      "messages_per_minute": 10,
      "schedule_windows": [{ "start": "09:00", "end": "20:00" }],
      "whatsapp_sender_id": 7,
      "whatsapp_template_id": 15,
      "text_variable_mapping": { "1": "customer_name" },
      "fallback_channel": null
    }
  }
  ```
</ResponseExample>


# Delete campaign
Source: https://docs.autocalls.ai/api-reference/campaigns/delete-campaign

DELETE /user/campaign/{id}
Delete a specific campaign

This endpoint allows you to delete a campaign that belongs to the authenticated user. If the campaign is currently running, it is stopped automatically before deletion.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the campaign to delete
</ParamField>

### Response

<ResponseField name="message" type="string">
  Confirmation message indicating the campaign was deleted successfully
</ResponseField>

### Error Responses

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message when the campaign is not found or doesn't belong to the authenticated user
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "message": "Campaign deleted successfully"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Campaign not found"
  }
  ```
</ResponseExample>

### Notes

* Only campaigns that belong to the authenticated user can be deleted
* Running campaigns are stopped automatically before deletion
* All leads attached to the campaign are removed
* Phone number assignments on the campaign are released


# Get campaign
Source: https://docs.autocalls.ai/api-reference/campaigns/get-campaign

GET /user/campaign/{id}
Get a single campaign by ID

Returns one campaign you own. Response `data` uses the same fields as [List campaigns](/api-reference/campaigns/get-campaigns).

### Path parameters

<ParamField type="integer">
  Campaign ID
</ParamField>

### Response

<ResponseField name="data" type="object">
  Full campaign object including `channel`, `schedule_windows`, WhatsApp/SMS config, and fallback fields.
</ResponseField>

### Error responses

<ResponseField name="404 Not Found">
  Campaign does not exist or does not belong to you.
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": {
      "id": 2,
      "name": "WhatsApp Follow-up",
      "channel": "whatsapp",
      "status": "draft",
      "assistant_id": null,
      "timezone": "UTC",
      "max_calls_in_parallel": 3,
      "messages_per_minute": 10,
      "schedule_windows": [{ "start": "09:00", "end": "20:00" }],
      "scheduled_start_at": null,
      "allowed_hours_start_time": "09:00",
      "allowed_hours_end_time": "20:00",
      "allowed_days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
      "max_retries": 3,
      "retry_interval": 60,
      "retry_on_voicemail": false,
      "retry_on_goal_incomplete": false,
      "goal_completion_variable": null,
      "mark_complete_when_no_leads": true,
      "phone_number_ids": [],
      "whatsapp_sender_id": 7,
      "whatsapp_template_id": 15,
      "sms_from_phone_number_id": null,
      "sms_body": null,
      "text_variable_mapping": { "1": "customer_name" },
      "fallback_channel": null,
      "fallback_whatsapp_sender_id": null,
      "fallback_whatsapp_template_id": null,
      "fallback_sms_from_phone_number_id": null,
      "fallback_sms_body": null,
      "fallback_variable_mapping": null,
      "created_at": "2026-07-24 10:00:00",
      "updated_at": "2026-07-24 10:00:00"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Campaign not found"
  }
  ```
</ResponseExample>


# List campaigns
Source: https://docs.autocalls.ai/api-reference/campaigns/get-campaigns

GET /user/campaigns
List all campaigns (call, WhatsApp, SMS)

Returns every campaign you own, including channel, schedule windows, WhatsApp/SMS config, and optional call→text fallback settings.

### Response

Returns a JSON **array** of campaign objects.

<ResponseField name="id" type="integer">
  Campaign ID
</ResponseField>

<ResponseField name="name" type="string">
  Campaign name
</ResponseField>

<ResponseField name="channel" type="string">
  `call`, `whatsapp`, or `sms`
</ResponseField>

<ResponseField name="status" type="string">
  e.g. `draft`, `scheduled`, `in-progress`, `paused`, `completed`
</ResponseField>

<ResponseField name="assistant_id" type="integer">
  OUTBOUND assistant ID (call campaigns). `null` for text campaigns.
</ResponseField>

<ResponseField name="timezone" type="string">
  IANA timezone for the send/call window
</ResponseField>

<ResponseField name="max_calls_in_parallel" type="integer">
  Concurrent call slots (call campaigns)
</ResponseField>

<ResponseField name="messages_per_minute" type="integer">
  Per-campaign text send rate (WhatsApp/SMS). WhatsApp also uses a user-wide in-flight pool of 10.
</ResponseField>

<ResponseField name="schedule_windows" type="array">
  Daily windows `[{ "start": "HH:MM", "end": "HH:MM" }]`. Overnight allowed when end \< start.
</ResponseField>

<ResponseField name="scheduled_start_at" type="string">
  ISO datetime for auto-start, or `null`
</ResponseField>

<ResponseField name="allowed_hours_start_time" type="string">
  Legacy window start (kept in sync with the first schedule window)
</ResponseField>

<ResponseField name="allowed_hours_end_time" type="string">
  Legacy window end
</ResponseField>

<ResponseField name="allowed_days" type="array">
  Weekdays when sending/calling is allowed
</ResponseField>

<ResponseField name="max_retries" type="integer">
  Max retries per lead
</ResponseField>

<ResponseField name="retry_interval" type="integer">
  Minutes between retries
</ResponseField>

<ResponseField name="retry_on_voicemail" type="boolean">
  Call campaigns: retry on voicemail
</ResponseField>

<ResponseField name="retry_on_goal_incomplete" type="boolean">
  Call campaigns: retry until goal variable is true
</ResponseField>

<ResponseField name="goal_completion_variable" type="string">
  Boolean post-call variable name, or `null`
</ResponseField>

<ResponseField name="mark_complete_when_no_leads" type="boolean">
  Auto-complete when no work remains
</ResponseField>

<ResponseField name="phone_number_ids" type="array">
  Outbound from-number IDs (call campaigns)
</ResponseField>

<ResponseField name="whatsapp_sender_id" type="integer">
  WhatsApp sender ID, or `null`
</ResponseField>

<ResponseField name="whatsapp_template_id" type="integer">
  WhatsApp template ID, or `null`
</ResponseField>

<ResponseField name="sms_from_phone_number_id" type="integer">
  SMS from-number ID, or `null`
</ResponseField>

<ResponseField name="sms_body" type="string">
  SMS body, or `null`
</ResponseField>

<ResponseField name="text_variable_mapping" type="object">
  WhatsApp template placeholder → lead variable map, or `null`
</ResponseField>

<ResponseField name="fallback_channel" type="string">
  Call→text fallback channel (`whatsapp` / `sms`), or `null`
</ResponseField>

<ResponseField name="fallback_whatsapp_sender_id" type="integer">
  Fallback WhatsApp sender, or `null`
</ResponseField>

<ResponseField name="fallback_whatsapp_template_id" type="integer">
  Fallback WhatsApp template, or `null`
</ResponseField>

<ResponseField name="fallback_sms_from_phone_number_id" type="integer">
  Fallback SMS from-number, or `null`
</ResponseField>

<ResponseField name="fallback_sms_body" type="string">
  Fallback SMS body, or `null`
</ResponseField>

<ResponseField name="fallback_variable_mapping" type="object">
  Fallback WhatsApp variable map, or `null`
</ResponseField>

<ResponseField name="created_at" type="string">
  Created timestamp in your account timezone
</ResponseField>

<ResponseField name="updated_at" type="string">
  Updated timestamp in your account timezone
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  [
    {
      "id": 1,
      "name": "Product Demo Campaign",
      "channel": "call",
      "status": "in-progress",
      "assistant_id": 42,
      "timezone": "Europe/Bucharest",
      "max_calls_in_parallel": 3,
      "messages_per_minute": null,
      "schedule_windows": [{ "start": "09:00", "end": "18:00" }],
      "scheduled_start_at": null,
      "allowed_hours_start_time": "09:00:00",
      "allowed_hours_end_time": "18:00:00",
      "allowed_days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
      "max_retries": 3,
      "retry_interval": 60,
      "retry_on_voicemail": false,
      "retry_on_goal_incomplete": false,
      "goal_completion_variable": null,
      "mark_complete_when_no_leads": true,
      "phone_number_ids": [11],
      "whatsapp_sender_id": null,
      "whatsapp_template_id": null,
      "sms_from_phone_number_id": null,
      "sms_body": null,
      "text_variable_mapping": null,
      "fallback_channel": "whatsapp",
      "fallback_whatsapp_sender_id": 7,
      "fallback_whatsapp_template_id": 15,
      "fallback_sms_from_phone_number_id": null,
      "fallback_sms_body": null,
      "fallback_variable_mapping": { "1": "customer_name" },
      "created_at": "2026-07-24 10:00:00",
      "updated_at": "2026-07-24 12:00:00"
    },
    {
      "id": 2,
      "name": "WhatsApp Follow-up",
      "channel": "whatsapp",
      "status": "draft",
      "assistant_id": null,
      "messages_per_minute": 10,
      "schedule_windows": [{ "start": "09:00", "end": "20:00" }],
      "whatsapp_sender_id": 7,
      "whatsapp_template_id": 15,
      "text_variable_mapping": { "1": "customer_name" },
      "fallback_channel": null
    }
  ]
  ```
</ResponseExample>


# Update campaign status
Source: https://docs.autocalls.ai/api-reference/campaigns/update-status

POST /user/campaigns/update-status
Start or stop a call, WhatsApp, or SMS campaign

Start or stop a campaign you own. Starting validates channel config (assistant / WhatsApp template / SMS number), schedule, and balance. Disabled channels (for example SMS when temporarily unavailable) cannot be started.

### Request body

<ParamField type="integer">
  The ID of the campaign to update
</ParamField>

<ParamField type="string">
  `start` or `stop`
</ParamField>

### Response

<ResponseField name="message" type="string">
  Human-readable outcome
</ResponseField>

<ResponseField name="success" type="boolean">
  Whether the operation succeeded
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data properties">
    <ResponseField name="campaign_id" type="integer">
      Campaign ID
    </ResponseField>

    <ResponseField name="status" type="string">
      New status (e.g. `in-progress`, `paused`)
    </ResponseField>

    <ResponseField name="channel" type="string">
      `call`, `whatsapp`, or `sms`
    </ResponseField>
  </Expandable>
</ResponseField>


# Create Conversation
Source: https://docs.autocalls.ai/api-reference/conversations/create-conversation

POST /conversations
Create a new conversation session with an AI assistant

This endpoint creates a new conversation session with an AI assistant. Use this to initiate a text-based chat session through your web widget or application.

### Request Body

<ParamField type="string">
  The UUID of the assistant to start the conversation with. Must be a valid assistant UUID that exists in the system.
</ParamField>

<ParamField type="string">
  The type of conversation. Possible values:

  * `widget` - Web widget conversation (default, charged)
  * `test` - Test conversation (free, for development)
</ParamField>

<ParamField type="object">
  Custom variables to pass to the assistant. These variables can be used in the assistant's system prompt and initial message using `{{variable_name}}` syntax.

  Common use cases:

  * Pre-filling customer information from forms
  * Passing context from your application
  * Customizing assistant behavior per session
</ParamField>

### Response Fields

<ResponseField name="status" type="boolean">
  Indicates whether the request was successful
</ResponseField>

<ResponseField name="conversation_id" type="string">
  The unique UUID identifier for the created conversation. Use this ID for subsequent message requests.
</ResponseField>

<ResponseField name="history" type="array">
  The initial conversation history. If the assistant has an initial message configured, it will be included here.

  <Expandable title="Message object properties">
    <ResponseField name="role" type="string">
      The message role: `assistant` or `user`
    </ResponseField>

    <ResponseField name="content" type="string">
      The message content
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

<ResponseField name="status" type="boolean">
  Will be `false` when an error occurs
</ResponseField>

<ResponseField name="error" type="string">
  Error message describing what went wrong. Possible values:

  * `Assistant not found` - The provided assistant\_id does not exist
  * `Insufficient balance. Please top up your account.` - The assistant owner's account balance is too low
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.autocalls.ai/api/conversations" \
    -H "Content-Type: application/json" \
    -d '{
      "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "widget",
      "variables": {
        "customer_name": "John Smith",
        "company": "Acme Corp",
        "source": "pricing_page"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.autocalls.ai/api/conversations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      assistant_id: '550e8400-e29b-41d4-a716-446655440000',
      type: 'widget',
      variables: {
        customer_name: 'John Smith',
        company: 'Acme Corp',
        source: 'pricing_page'
      }
    })
  });

  const data = await response.json();
  console.log(data.conversation_id);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://app.autocalls.ai/api/conversations',
      json={
          'assistant_id': '550e8400-e29b-41d4-a716-446655440000',
          'type': 'widget',
          'variables': {
              'customer_name': 'John Smith',
              'company': 'Acme Corp',
              'source': 'pricing_page'
          }
      }
  )

  data = response.json()
  print(data['conversation_id'])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "status": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "history": [
      {
        "role": "assistant",
        "content": "Hello John Smith! Welcome to Acme Corp support. How can I help you today?"
      }
    ]
  }
  ```

  ```json 200 Success (No initial message) theme={null}
  {
    "status": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "history": []
  }
  ```

  ```json 404 Assistant Not Found theme={null}
  {
    "status": false,
    "error": "Assistant not found"
  }
  ```

  ```json 400 Insufficient Balance theme={null}
  {
    "status": false,
    "error": "Insufficient balance. Please top up your account."
  }
  ```
</ResponseExample>

## Pricing

* **Widget conversations**: \$0.01 per user message
* **Test conversations**: Free (for development and testing)

## Next Steps

After creating a conversation, use the [Send Message](/api-reference/conversations/send-message) endpoint to exchange messages with the assistant.


# Disable AI
Source: https://docs.autocalls.ai/api-reference/conversations/disable-ai

POST /user/conversations/{uuid}/disable-ai
Disable AI replies for a specific conversation, allowing a human agent to take over

Disables AI responses for a conversation. Once disabled, the assistant will stop generating replies — any new messages in the conversation will be stored but not answered by the AI.

This is useful for **human takeover** flows: configure a mid-call tool or automation that calls this endpoint when a customer requests to speak with a human agent.

### Authentication

This endpoint requires your **API key** as a Bearer token.

### Path Parameters

<ParamField type="string">
  The unique UUID identifier of the conversation
</ParamField>

### Response Fields

<ResponseField name="status" type="boolean">
  `true` when the operation was successful
</ResponseField>

<ResponseField name="ai_enabled" type="boolean">
  Will always be `false` on success
</ResponseField>

### Error Responses

<ResponseField name="status" type="boolean">
  `false` when an error occurs
</ResponseField>

<ResponseField name="error" type="string">
  Error message. Possible values:

  * `Conversation not found` — the UUID does not exist or belongs to a different account
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.autocalls.ai/api/user/conversations/7c9e6679-7425-40de-944b-e07fc1f90ae7/disable-ai" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const conversationId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';

  const response = await fetch(
    `https://app.autocalls.ai/api/user/conversations/${conversationId}/disable-ai`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
      },
    }
  );

  const data = await response.json();
  console.log(data.ai_enabled); // false
  ```

  ```python Python theme={null}
  import requests

  conversation_id = '7c9e6679-7425-40de-944b-e07fc1f90ae7'

  response = requests.post(
      f'https://app.autocalls.ai/api/user/conversations/{conversation_id}/disable-ai',
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

  data = response.json()
  print(data['ai_enabled'])  # False
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "status": true,
    "ai_enabled": false
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "status": false,
    "error": "Conversation not found"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized"
  }
  ```
</ResponseExample>

## Human Takeover Flow

A common pattern is to configure a mid-call tool that triggers this endpoint when the customer asks to speak with a human:

1. Create a mid-call tool (e.g. `transfer_to_human`) with a webhook pointing to your ActivePieces or automation flow
2. In your automation flow, call `POST /user/conversations/{uuid}/disable-ai` using your API key
3. Notify your support team (e.g. via Slack, email, or CRM) with the conversation UUID
4. The AI stops responding — your agent takes over by sending messages directly

To re-enable AI later, use the [Enable AI](/api-reference/conversations/enable-ai) endpoint.


# Enable AI
Source: https://docs.autocalls.ai/api-reference/conversations/enable-ai

POST /user/conversations/{uuid}/enable-ai
Re-enable AI replies for a conversation after a human takeover

Re-enables AI responses for a conversation that was previously disabled via the [Disable AI](/api-reference/conversations/disable-ai) endpoint. The assistant will resume responding to new messages from this point forward.

### Authentication

This endpoint requires your **API key** as a Bearer token.

### Path Parameters

<ParamField type="string">
  The unique UUID identifier of the conversation
</ParamField>

### Response Fields

<ResponseField name="status" type="boolean">
  `true` when the operation was successful
</ResponseField>

<ResponseField name="ai_enabled" type="boolean">
  Will always be `true` on success
</ResponseField>

### Error Responses

<ResponseField name="status" type="boolean">
  `false` when an error occurs
</ResponseField>

<ResponseField name="error" type="string">
  Error message. Possible values:

  * `Conversation not found` — the UUID does not exist or belongs to a different account
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.autocalls.ai/api/user/conversations/7c9e6679-7425-40de-944b-e07fc1f90ae7/enable-ai" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const conversationId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';

  const response = await fetch(
    `https://app.autocalls.ai/api/user/conversations/${conversationId}/enable-ai`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
      },
    }
  );

  const data = await response.json();
  console.log(data.ai_enabled); // true
  ```

  ```python Python theme={null}
  import requests

  conversation_id = '7c9e6679-7425-40de-944b-e07fc1f90ae7'

  response = requests.post(
      f'https://app.autocalls.ai/api/user/conversations/{conversation_id}/enable-ai',
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

  data = response.json()
  print(data['ai_enabled'])  # True
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "status": true,
    "ai_enabled": true
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "status": false,
    "error": "Conversation not found"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized"
  }
  ```
</ResponseExample>


# Get Conversation
Source: https://docs.autocalls.ai/api-reference/conversations/get-conversation

GET /conversations/{uuid}
Retrieve the message history of a conversation

This endpoint retrieves the complete message history of an existing conversation. Use this to display previous messages when resuming a conversation or to review conversation content.

### Path Parameters

<ParamField type="string">
  The unique UUID identifier of the conversation to retrieve
</ParamField>

### Response Fields

<ResponseField name="status" type="boolean">
  Indicates whether the request was successful
</ResponseField>

<ResponseField name="history" type="array">
  Array of messages in the conversation, ordered chronologically (oldest first).

  <Expandable title="Message object properties">
    <ResponseField name="role" type="string">
      The message role: `assistant` or `user`
    </ResponseField>

    <ResponseField name="content" type="string">
      The message content
    </ResponseField>

    <ResponseField name="function_calls" type="array">
      Optional. Array of function calls made by the assistant during this message (e.g., calendar bookings, API calls).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="variables" type="object">
  Custom variables associated with the conversation (key-value pairs). Returns `null` if no variables are set.
</ResponseField>

<ResponseField name="external_identifier" type="string">
  Your external system's identifier for this conversation. Only present for `api` type conversations that have an external identifier set.
</ResponseField>

<ResponseField name="whatsapp_sender" type="object">
  The WhatsApp business sender information. Only present for `whatsapp` type conversations.

  <Expandable title="whatsapp_sender properties">
    <ResponseField name="name" type="string">
      The WhatsApp sender's display name (business name)
    </ResponseField>

    <ResponseField name="phone" type="string">
      The WhatsApp sender's phone number
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="customer" type="object">
  The customer information. Only present for `whatsapp` type conversations.

  <Expandable title="customer properties">
    <ResponseField name="name" type="string">
      The customer's name (if available)
    </ResponseField>

    <ResponseField name="phone" type="string">
      The customer's phone number
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

<ResponseField name="status" type="boolean">
  Will be `false` when an error occurs
</ResponseField>

<ResponseField name="error" type="string">
  Error message. Possible values:

  * `Conversation not found` - The provided UUID does not match any conversation
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.autocalls.ai/api/conversations/7c9e6679-7425-40de-944b-e07fc1f90ae7"
  ```

  ```javascript JavaScript theme={null}
  const conversationId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';

  const response = await fetch(
    `https://app.autocalls.ai/api/conversations/${conversationId}`
  );

  const data = await response.json();
  console.log(data.history);
  ```

  ```python Python theme={null}
  import requests

  conversation_id = '7c9e6679-7425-40de-944b-e07fc1f90ae7'

  response = requests.get(
      f'https://app.autocalls.ai/api/conversations/{conversation_id}'
  )

  data = response.json()
  print(data['history'])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "status": true,
    "history": [
      {
        "role": "assistant",
        "content": "Hello! Welcome to our support. How can I help you today?"
      },
      {
        "role": "user",
        "content": "I'd like to schedule a demo"
      },
      {
        "role": "assistant",
        "content": "I'd be happy to help you schedule a demo! I have availability tomorrow at 2 PM or Thursday at 10 AM. Which works better for you?",
        "function_calls": [
          {
            "name": "check_calendar_availability",
            "arguments": {
              "date_range": "next_7_days"
            },
            "result": {
              "available_slots": ["2025-01-10 14:00", "2025-01-12 10:00"]
            }
          }
        ]
      },
      {
        "role": "user",
        "content": "Thursday at 10 AM works for me"
      },
      {
        "role": "assistant",
        "content": "I've scheduled your demo for Thursday, January 12th at 10 AM. You'll receive a calendar invitation shortly. Is there anything specific you'd like us to cover during the demo?",
        "function_calls": [
          {
            "name": "book_appointment",
            "arguments": {
              "datetime": "2025-01-12T10:00:00",
              "title": "Product Demo"
            },
            "result": {
              "success": true,
              "booking_id": "abc123"
            }
          }
        ]
      }
    ],
    "variables": {
      "user_name": "Jane Smith",
      "plan": "premium"
    }
  }
  ```

  ```json 200 API Conversation with External ID theme={null}
  {
    "status": true,
    "history": [
      {
        "role": "assistant",
        "content": "Hi! I'm following up on your recent inquiry. How can I help you today?"
      },
      {
        "role": "user",
        "content": "I wanted to know more about your enterprise plan"
      }
    ],
    "variables": {
      "lead_id": "12345",
      "source": "website"
    },
    "external_identifier": "crm-lead-12345"
  }
  ```

  ```json 200 WhatsApp Conversation theme={null}
  {
    "status": true,
    "history": [
      {
        "role": "user",
        "content": "Hi, I need help with my order"
      },
      {
        "role": "assistant",
        "content": "Hello! I'd be happy to help you with your order. Could you please provide your order number?"
      }
    ],
    "variables": null,
    "whatsapp_sender": {
      "name": "Acme Corp Support",
      "phone": "+14155551234"
    },
    "customer": {
      "name": "John Doe",
      "phone": "+14155559876"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "status": false,
    "error": "Conversation not found"
  }
  ```
</ResponseExample>

## Variables

All conversations include a `variables` field containing custom key-value pairs set when the conversation was created. Use variables to:

* Store user context (name, plan, preferences)
* Track lead information from your forms
* Pass custom data for personalized AI responses

## API Conversations

For API-created conversations, the response may include an `external_identifier` field if one was set when creating the conversation. This allows you to:

* Link conversations to your CRM leads or contacts
* Track conversations across your internal systems
* Look up conversations by your external reference

## WhatsApp Conversations

For WhatsApp conversations, the response includes additional fields:

* **whatsapp\_sender**: The business WhatsApp number that handled the conversation (name and phone)
* **customer**: The customer who initiated or received the conversation (name and phone)

These fields help you identify the parties involved when integrating WhatsApp conversations with your CRM or support systems.

## Use Cases

* **Resume conversations**: Retrieve history when a user returns to continue a conversation
* **Analytics**: Review conversation content for quality assurance
* **CRM Integration**: Use `external_identifier` and `variables` to sync with your CRM
* **WhatsApp tracking**: Match conversations to customers using their phone numbers


# List Conversations
Source: https://docs.autocalls.ai/api-reference/conversations/list-conversations

GET /user/conversations
List all conversations for the authenticated user with filtering and cursor pagination

This endpoint returns a cursor-paginated list of conversations belonging to the authenticated user's assistants. Use this to display conversation history, filter by type, or integrate with your CRM.

<Note>
  This endpoint uses cursor-based pagination for better performance with large datasets. Use `next_cursor` and `prev_cursor` to navigate between pages.
</Note>

### Query Parameters

<ParamField type="string">
  Filter conversations by type. Possible values: `test`, `widget`, `whatsapp`, `api`
</ParamField>

<ParamField type="integer">
  Filter conversations by assistant ID (must belong to the authenticated user)
</ParamField>

<ParamField type="string">
  Filter conversations by customer phone number (exact match). Useful for finding all conversations with a specific customer.
</ParamField>

<ParamField type="string">
  Filter conversations by WhatsApp sender phone number (exact match). Useful for finding all conversations from a specific WhatsApp business number.
</ParamField>

<ParamField type="string">
  Filter conversations by external identifier. Useful for finding conversations linked to your external system records.
</ParamField>

<ParamField type="integer">
  Number of conversations per page (1-100, default: 15)
</ParamField>

<ParamField type="string">
  Cursor for pagination. Use `next_cursor` or `prev_cursor` from a previous response.
</ParamField>

### Response Fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      The unique UUID identifier of the conversation
    </ResponseField>

    <ResponseField name="assistant_id" type="string">
      The UUID of the assistant handling this conversation
    </ResponseField>

    <ResponseField name="assistant_name" type="string">
      The name of the assistant handling this conversation
    </ResponseField>

    <ResponseField name="type" type="string">
      The conversation type: `test`, `widget`, `whatsapp`, or `api`
    </ResponseField>

    <ResponseField name="variables" type="object">
      Custom variables associated with the conversation (key-value pairs)
    </ResponseField>

    <ResponseField name="external_identifier" type="string">
      Your external system's identifier for this conversation. Only present for `api` type conversations that have an external identifier set.
    </ResponseField>

    <ResponseField name="message_count" type="integer">
      Total number of messages in the conversation
    </ResponseField>

    <ResponseField name="total_cost" type="number">
      The total cost of the conversation in USD
    </ResponseField>

    <ResponseField name="ai_enabled" type="boolean">
      Whether AI responses are enabled for this conversation
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The date and time when the conversation was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      The date and time when the conversation was last updated
    </ResponseField>

    <ResponseField name="whatsapp_sender" type="object">
      The WhatsApp business sender information. Only present for `whatsapp` type conversations.

      <Expandable title="whatsapp_sender properties">
        <ResponseField name="name" type="string">
          The WhatsApp sender's display name (business name)
        </ResponseField>

        <ResponseField name="phone" type="string">
          The WhatsApp sender's phone number
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="customer" type="object">
      The customer information. Only present for `whatsapp` type conversations.

      <Expandable title="customer properties">
        <ResponseField name="name" type="string">
          The customer's name (if available)
        </ResponseField>

        <ResponseField name="phone" type="string">
          The customer's phone number
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Cursor to fetch the next page of results. Pass this as the `cursor` parameter in your next request. `null` if there are no more results.
</ResponseField>

<ResponseField name="prev_cursor" type="string">
  Cursor to fetch the previous page of results. `null` if this is the first page.
</ResponseField>

<ResponseField name="per_page" type="integer">
  Number of items per page
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.autocalls.ai/api/user/conversations?type=whatsapp&per_page=10" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Filter by customer phone theme={null}
  curl -X GET "https://app.autocalls.ai/api/user/conversations?customer_phone=+14155559876" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Filter by WhatsApp sender theme={null}
  curl -X GET "https://app.autocalls.ai/api/user/conversations?whatsapp_sender_phone=+14155551234" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.autocalls.ai/api/user/conversations?type=whatsapp&per_page=10',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  // Fetch next page using cursor
  if (data.next_cursor) {
    const nextPage = await fetch(
      `https://app.autocalls.ai/api/user/conversations?cursor=${data.next_cursor}`,
      { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
    );
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://app.autocalls.ai/api/user/conversations',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={
          'type': 'whatsapp',
          'per_page': 10
      }
  )

  data = response.json()

  # Fetch next page using cursor
  if data.get('next_cursor'):
      next_response = requests.get(
          'https://app.autocalls.ai/api/user/conversations',
          headers={'Authorization': 'Bearer YOUR_API_KEY'},
          params={'cursor': data['next_cursor']}
      )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "assistant_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "assistant_name": "Support Assistant",
        "type": "widget",
        "variables": {
          "user_name": "Jane Smith",
          "plan": "premium"
        },
        "message_count": 12,
        "total_cost": 0.0045,
        "ai_enabled": true,
        "created_at": "2025-01-25 14:30:00",
        "updated_at": "2025-01-25 14:45:22"
      },
      {
        "id": "8d0f7780-8536-51ef-055c-f18fd2g01bf8",
        "assistant_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "assistant_name": "Support Assistant",
        "type": "whatsapp",
        "variables": null,
        "message_count": 8,
        "total_cost": 0.0032,
        "ai_enabled": true,
        "created_at": "2025-01-25 10:15:00",
        "updated_at": "2025-01-25 10:28:45",
        "whatsapp_sender": {
          "name": "Acme Corp Support",
          "phone": "+14155551234"
        },
        "customer": {
          "name": "John Doe",
          "phone": "+14155559876"
        }
      },
      {
        "id": "9e1g8891-9647-62fg-166d-g29ge3h12cg9",
        "assistant_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "assistant_name": "Support Assistant",
        "type": "api",
        "variables": {
          "lead_id": "12345",
          "source": "website"
        },
        "external_identifier": "crm-lead-12345",
        "message_count": 5,
        "total_cost": 0.0021,
        "ai_enabled": true,
        "created_at": "2025-01-25 09:00:00",
        "updated_at": "2025-01-25 09:15:30"
      }
    ],
    "path": "https://app.autocalls.ai/api/user/conversations",
    "per_page": 15,
    "next_cursor": "eyJpZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
    "prev_cursor": null
  }
  ```
</ResponseExample>

## Conversation Types

| Type       | Description                                                      |
| ---------- | ---------------------------------------------------------------- |
| `test`     | Internal test conversations from the assistant testing interface |
| `widget`   | Conversations from the web chat widget                           |
| `whatsapp` | WhatsApp Business conversations                                  |
| `api`      | Conversations created via the API                                |

## Filter Parameters

All filter parameters use indexed columns for efficient querying:

| Parameter               | Description                     | Use Case                                               |
| ----------------------- | ------------------------------- | ------------------------------------------------------ |
| `type`                  | Filter by conversation type     | Get only WhatsApp or widget conversations              |
| `assistant_id`          | Filter by specific assistant    | View conversations for a single assistant              |
| `customer_phone`        | Filter by customer phone number | Find all conversations with a specific customer        |
| `whatsapp_sender_phone` | Filter by WhatsApp sender phone | Find all conversations from a specific business number |
| `external_identifier`   | Filter by your external ID      | Link conversations to your CRM records                 |

## WhatsApp Conversation Details

For WhatsApp conversations, the response includes additional fields:

* **whatsapp\_sender**: The business WhatsApp number that handled the conversation (your WhatsApp sender's name and phone)
* **customer**: The customer who initiated or received the conversation (their name and phone number)

These fields are only present for `whatsapp` type conversations and help you identify the parties involved when integrating with your CRM or support systems.

## API Conversation Details

For API-created conversations, you can set an `external_identifier` when creating the conversation. This identifier is returned in the response and can be used to:

* Link conversations to your CRM leads or contacts
* Track conversations across your internal systems
* Filter conversations by your external reference

## Use Cases

* **Analytics Dashboard**: Display conversation metrics and trends
* **CRM Integration**: Sync conversation data with your customer database using `external_identifier`
* **Customer Lookup**: Find all conversations with a specific customer using `customer_phone`
* **Quality Monitoring**: Review conversation volumes by type and assistant
* **Billing Review**: Track conversation costs across your organization


# Send Message
Source: https://docs.autocalls.ai/api-reference/conversations/send-message

POST /conversations/{uuid}/messages
Send a message in an existing conversation and receive the assistant's response

This endpoint sends a user message to an existing conversation and returns the assistant's response. The assistant processes the message using the configured AI model and any available tools.

### Path Parameters

<ParamField type="string">
  The unique UUID identifier of the conversation
</ParamField>

### Request Body

<ParamField type="string">
  The user's message to send to the assistant. Maximum length: 2000 characters.
</ParamField>

### Response Fields

<ResponseField name="status" type="boolean">
  Indicates whether the request was successful
</ResponseField>

<ResponseField name="message" type="string">
  The assistant's response to the user's message
</ResponseField>

<ResponseField name="function_calls" type="array">
  Array of function calls made by the assistant while processing the message. Empty array if no functions were called.

  <Expandable title="Function call object properties">
    <ResponseField name="name" type="string">
      The name of the function that was called
    </ResponseField>

    <ResponseField name="arguments" type="object">
      The arguments passed to the function
    </ResponseField>

    <ResponseField name="result" type="object">
      The result returned by the function
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

<ResponseField name="status" type="boolean">
  Will be `false` when an error occurs
</ResponseField>

<ResponseField name="error" type="string">
  Error message. Possible values:

  * `Conversation not found` - The provided UUID does not match any conversation
  * `Insufficient balance. Please top up your account.` - The assistant owner's account balance is too low
  * `Failed to process message: [details]` - An error occurred while processing the message
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.autocalls.ai/api/conversations/7c9e6679-7425-40de-944b-e07fc1f90ae7/messages" \
    -H "Content-Type: application/json" \
    -d '{
      "message": "I would like to schedule a demo for next week"
    }'
  ```

  ```javascript JavaScript theme={null}
  const conversationId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';

  const response = await fetch(
    `https://app.autocalls.ai/api/conversations/${conversationId}/messages`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        message: 'I would like to schedule a demo for next week'
      })
    }
  );

  const data = await response.json();
  console.log(data.message);
  ```

  ```python Python theme={null}
  import requests

  conversation_id = '7c9e6679-7425-40de-944b-e07fc1f90ae7'

  response = requests.post(
      f'https://app.autocalls.ai/api/conversations/{conversation_id}/messages',
      json={
          'message': 'I would like to schedule a demo for next week'
      }
  )

  data = response.json()
  print(data['message'])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "status": true,
    "message": "I'd be happy to help you schedule a demo! I have availability on Monday at 2 PM, Wednesday at 10 AM, or Friday at 3 PM. Which time works best for you?",
    "function_calls": []
  }
  ```

  ```json 200 Success (With Function Calls) theme={null}
  {
    "status": true,
    "message": "I've checked our calendar and found several available slots for next week. I can offer you Monday at 2 PM, Wednesday at 10 AM, or Friday at 3 PM. Which would you prefer?",
    "function_calls": [
      {
        "name": "check_calendar_availability",
        "arguments": {
          "start_date": "2025-01-13",
          "end_date": "2025-01-17"
        },
        "result": {
          "available_slots": [
            "2025-01-13 14:00",
            "2025-01-15 10:00",
            "2025-01-17 15:00"
          ]
        }
      }
    ]
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "status": false,
    "error": "Conversation not found"
  }
  ```

  ```json 400 Insufficient Balance theme={null}
  {
    "status": false,
    "error": "Insufficient balance. Please top up your account."
  }
  ```

  ```json 400 Processing Error theme={null}
  {
    "status": false,
    "error": "Failed to process message: Connection timeout"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The message field is required.",
    "errors": {
      "message": ["The message field is required."]
    }
  }
  ```
</ResponseExample>

## Pricing

Each user message in a **widget** conversation costs **\$0.01**. Test conversations are free.

## Function Calls

The assistant may execute functions during message processing, such as:

* **Calendar operations**: Checking availability, booking appointments
* **Knowledge base queries**: Searching documentation or FAQs
* **Custom integrations**: Calling your configured webhook endpoints

Function call results are included in the response so you can display relevant information to the user or track actions taken.

## Best Practices

1. **Handle errors gracefully**: Display user-friendly messages when errors occur
2. **Show loading states**: The assistant may take a few seconds to respond, especially when executing functions
3. **Preserve conversation ID**: Store the conversation UUID to allow users to resume conversations
4. **Respect rate limits**: Implement appropriate delays between messages if needed


# Create folder
Source: https://docs.autocalls.ai/api-reference/folders/create-folder

POST /user/folder
Create a folder to organize your assistants

Create a folder to group your assistants. Assign assistants to a folder with the `folder_id` field on the [Create assistant](/api-reference/assistants/create-assistant) and [Update assistant](/api-reference/assistants/update-assistant) endpoints.

### Request Body

<ParamField type="string">
  The folder name (max 255 characters). Must be unique within your account.
</ParamField>

<ParamField type="string">
  A color for the folder badge. One of: `gray`, `slate`, `red`, `orange`, `amber`, `green`, `teal`, `blue`, `purple`, `pink`.
</ParamField>

### Response

<ResponseField name="message" type="string">Success message</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">The unique identifier of the created folder</ResponseField>
    <ResponseField name="name" type="string">The folder name</ResponseField>
    <ResponseField name="color" type="string">The folder color (or `null`)</ResponseField>
    <ResponseField name="assistants_count" type="integer">Number of assistants in this folder (always `0` for a new folder)</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Success Response theme={null}
  {
    "message": "Folder created successfully",
    "data": { "id": 12, "name": "Acme Corp", "color": "blue", "assistants_count": 0 }
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The name has already been taken.",
    "errors": { "name": ["The name has already been taken."] }
  }
  ```
</ResponseExample>


# Delete folder
Source: https://docs.autocalls.ai/api-reference/folders/delete-folder

DELETE /user/folder/{id}
Delete a folder

Delete a folder. Assistants that were in the folder are **not** deleted — they simply become uncategorized.

### Path Parameters

<ParamField type="integer">
  The folder ID. Must belong to your account.
</ParamField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  { "message": "Folder deleted successfully" }
  ```

  ```json 404 Not Found theme={null}
  { "message": "Folder not found" }
  ```
</ResponseExample>


# List folders
Source: https://docs.autocalls.ai/api-reference/folders/get-folders

GET /user/folders
List the folders in your account

Folders let you group assistants (for example, by client or brand). Each assistant can belong to a single folder. Folders are private to your account.

This endpoint returns your folders (paginated), each with the number of assistants it contains.

### Query Parameters

<ParamField type="integer">
  Number of folders per page (1-100, default: 15)
</ParamField>

<ParamField type="integer">
  Page number (default: 1)
</ParamField>

### Response fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">The unique identifier of the folder</ResponseField>
    <ResponseField name="name" type="string">The folder name</ResponseField>
    <ResponseField name="color" type="string">The folder color (or `null`)</ResponseField>
    <ResponseField name="assistants_count" type="integer">Number of assistants in this folder</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "data": [
      { "id": 12, "name": "Acme Corp", "color": "blue", "assistants_count": 4 },
      { "id": 18, "name": "Globex", "color": "teal", "assistants_count": 0 }
    ],
    "current_page": 1,
    "per_page": 15,
    "total": 2
  }
  ```
</ResponseExample>


# Update folder
Source: https://docs.autocalls.ai/api-reference/folders/update-folder

PUT /user/folder/{id}
Rename a folder or change its color

Update a folder's name or color. Only the fields you send are changed.

### Path Parameters

<ParamField type="integer">
  The folder ID. Must belong to your account.
</ParamField>

### Request Body

<ParamField type="string">
  New name (max 255 characters). Must be unique within your account.
</ParamField>

<ParamField type="string">
  New color. One of: `gray`, `slate`, `red`, `orange`, `amber`, `green`, `teal`, `blue`, `purple`, `pink`. Send `null` to clear it.
</ParamField>

### Response

<ResponseField name="message" type="string">Success message</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">The folder ID</ResponseField>
    <ResponseField name="name" type="string">The folder name</ResponseField>
    <ResponseField name="color" type="string">The folder color (or `null`)</ResponseField>
    <ResponseField name="assistants_count" type="integer">Number of assistants in this folder</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "message": "Folder updated successfully",
    "data": { "id": 12, "name": "Acme Inc.", "color": "pink", "assistants_count": 4 }
  }
  ```

  ```json 404 Not Found theme={null}
  { "message": "Folder not found" }
  ```
</ResponseExample>


# Introduction
Source: https://docs.autocalls.ai/api-reference/introduction

Welcome to the Autocalls API

Welcome to the Autocalls API documentation. Our API allows you to programmatically interact with the Autocalls platform, enabling you to create and manage leads, schedule calls, and more.

## Base URL

All API requests should be made to the following base URL:

```
https://app.autocalls.ai/api
```


# Create document
Source: https://docs.autocalls.ai/api-reference/knowledgebases/create-document

POST /user/knowledgebases/{knowledgebaseId}/documents
Add a new document to a knowledgebase

This endpoint creates a new document in a knowledgebase. Documents are processed asynchronously - the endpoint returns immediately while processing continues in the background.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the knowledgebase
</ParamField>

### Request Body

<ParamField type="string">
  The name of the document (max 255 characters)
</ParamField>

<ParamField type="string">
  Optional description of the document (max 255 characters)
</ParamField>

<ParamField type="string">
  Document type: `website`, `pdf`, `txt`, or `docx`
</ParamField>

#### Website Documents

<ParamField type="string">
  The main URL to scrape. Required if `links` is not provided.
</ParamField>

<ParamField type="array">
  Array of specific URLs to scrape. Required if `url` is not provided.

  <Expandable title="links properties">
    <ParamField type="string">
      A valid URL to include in the document
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="integer">
  Maximum number of relative links to follow when scraping (1-50)
</ParamField>

#### File Documents (PDF, TXT, DOCX)

<ParamField type="file">
  The file to upload (max 20MB). Use `multipart/form-data` encoding.
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  The created document object

  <Expandable title="data properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the document
    </ResponseField>

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

    <ResponseField name="description" type="string">
      Description of the document
    </ResponseField>

    <ResponseField name="type" type="string">
      Document type
    </ResponseField>

    <ResponseField name="type_label" type="string">
      Human-readable type label
    </ResponseField>

    <ResponseField name="status" type="string">
      Processing status (will be `processing` initially)
    </ResponseField>

    <ResponseField name="status_label" type="string">
      Human-readable status label
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Website Document Created theme={null}
  {
    "message": "Document created successfully. Processing will begin shortly.",
    "data": {
      "id": 1,
      "name": "Company Website",
      "description": "Main website content",
      "type": "website",
      "type_label": "Website",
      "status": "processing",
      "status_label": "Processing",
      "created_at": "2025-01-08T10:30:00.000000Z"
    }
  }
  ```

  ```json 201 PDF Document Created theme={null}
  {
    "message": "Document created successfully. Processing will begin shortly.",
    "data": {
      "id": 2,
      "name": "Product Manual",
      "description": "User guide for our product",
      "type": "pdf",
      "type_label": "PDF",
      "status": "processing",
      "status_label": "Processing",
      "created_at": "2025-01-08T10:35:00.000000Z"
    }
  }
  ```

  ```json 404 Knowledgebase Not Found theme={null}
  {
    "error": "Knowledgebase not found."
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "A file is required for this document type.",
    "errors": {
      "file": [
        "A file is required for this document type."
      ]
    }
  }
  ```

  ```json 500 Processing Error theme={null}
  {
    "error": "Failed to create document. Please try again."
  }
  ```
</ResponseExample>

### Document Types

| Type      | Description                                 | Input               |
| --------- | ------------------------------------------- | ------------------- |
| `website` | Scrapes web pages and extracts text content | URL or list of URLs |
| `pdf`     | Extracts text from PDF files                | PDF file upload     |
| `txt`     | Plain text content                          | TXT file upload     |
| `docx`    | Extracts text from Word documents           | DOCX file upload    |

### Example: Creating a Website Document

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/user/knowledgebases/1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Website",
    "description": "Main website content",
    "type": "website",
    "url": "https://example.com",
    "relative_links_limit": 20
  }'
```

### Example: Uploading a PDF Document

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/user/knowledgebases/1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=Product Manual" \
  -F "description=User guide for our product" \
  -F "type=pdf" \
  -F "file=@/path/to/document.pdf"
```

<Note>
  Document processing is asynchronous. Poll the [get document](/api-reference/knowledgebases/get-document) endpoint to check when processing is complete.
</Note>


# Create knowledgebase
Source: https://docs.autocalls.ai/api-reference/knowledgebases/create-knowledgebase

POST /user/knowledgebases
Create a new knowledgebase

This endpoint creates a new knowledgebase. After creation, you can add documents to it using the [create document](/api-reference/knowledgebases/create-document) endpoint.

### Request Body

<ParamField type="string">
  The name of the knowledgebase (max 255 characters)
</ParamField>

<ParamField type="string">
  Optional description of the knowledgebase (max 255 characters)
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  The created knowledgebase object

  <Expandable title="data properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the knowledgebase
    </ResponseField>

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

    <ResponseField name="description" type="string">
      Description of the knowledgebase
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status (will be `empty` for new knowledgebases)
    </ResponseField>

    <ResponseField name="status_label" type="string">
      Human-readable status label
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "message": "Knowledgebase created successfully.",
    "data": {
      "id": 1,
      "name": "Product Documentation",
      "description": "Technical documentation for our products",
      "status": "empty",
      "status_label": "Empty",
      "created_at": "2025-01-08T10:30:00.000000Z",
      "updated_at": "2025-01-08T10:30:00.000000Z"
    }
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The name field is required.",
    "errors": {
      "name": [
        "The name field is required."
      ]
    }
  }
  ```

  ```json 500 Error theme={null}
  {
    "error": "Failed to create knowledgebase. Please try again."
  }
  ```
</ResponseExample>

### Next Steps

After creating a knowledgebase, you'll want to:

1. **Add documents** - Use the [create document](/api-reference/knowledgebases/create-document) endpoint to add content
2. **Wait for processing** - Documents are processed asynchronously
3. **Attach to assistant** - Use the [update assistant](/api-reference/assistants/update-assistant) endpoint to attach the knowledgebase


# Delete document
Source: https://docs.autocalls.ai/api-reference/knowledgebases/delete-document

DELETE /user/knowledgebases/{knowledgebaseId}/documents/{documentId}
Delete a document from a knowledgebase

This endpoint permanently deletes a document from a knowledgebase. The document's vector embeddings are also removed from the vector database.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the knowledgebase
</ParamField>

<ParamField type="integer">
  The unique identifier of the document to delete
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "message": "Document deleted successfully."
  }
  ```

  ```json 404 Knowledgebase Not Found theme={null}
  {
    "error": "Knowledgebase not found."
  }
  ```

  ```json 404 Document Not Found theme={null}
  {
    "error": "Document not found."
  }
  ```

  ```json 500 Error theme={null}
  {
    "error": "Failed to delete document. Please try again."
  }
  ```
</ResponseExample>

### What Gets Deleted

When you delete a document:

* **Document record** is removed from the database
* **Vector embeddings** are deleted from the vector database
* **Processed content** is removed from external document stores
* **Parent knowledgebase status** is updated automatically

<Warning>
  This action is irreversible. The document and all its processed content will be permanently deleted.
</Warning>

<Note>
  If this was the last document in the knowledgebase, the knowledgebase status will change to `empty`.
</Note>


# Delete knowledgebase
Source: https://docs.autocalls.ai/api-reference/knowledgebases/delete-knowledgebase

DELETE /user/knowledgebases/{id}
Delete a knowledgebase and all its documents

This endpoint permanently deletes a knowledgebase and all its associated documents. This action cannot be undone.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the knowledgebase to delete
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "message": "Knowledgebase deleted successfully."
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Knowledgebase not found."
  }
  ```
</ResponseExample>

### What Gets Deleted

When you delete a knowledgebase:

* **All documents** in the knowledgebase are permanently deleted
* **Vector embeddings** are removed from the vector database
* **Document store data** is cleaned up from external services

### What Happens to Attached Assistants

Any assistants that were using this knowledgebase will have their knowledgebase reference removed. They will continue to function but without the knowledgebase context.

<Warning>
  This action is irreversible. All documents and their processed content will be permanently deleted. Make sure you want to delete this knowledgebase before proceeding.
</Warning>


# Get document
Source: https://docs.autocalls.ai/api-reference/knowledgebases/get-document

GET /user/knowledgebases/{knowledgebaseId}/documents/{documentId}
Get a single document by ID

This endpoint returns the details of a specific document within a knowledgebase.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the knowledgebase
</ParamField>

<ParamField type="integer">
  The unique identifier of the document
</ParamField>

### Response

<ResponseField name="data" type="object">
  The document object

  <Expandable title="document properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the document
    </ResponseField>

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

    <ResponseField name="description" type="string">
      Optional description of the document
    </ResponseField>

    <ResponseField name="type" type="string">
      Document type: `website`, `pdf`, `txt`, or `docx`
    </ResponseField>

    <ResponseField name="type_label" type="string">
      Human-readable type label
    </ResponseField>

    <ResponseField name="status" type="string">
      Processing status: `processing`, `active`, or `failed`
    </ResponseField>

    <ResponseField name="status_label" type="string">
      Human-readable status label
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": {
      "id": 1,
      "name": "Product Manual",
      "description": "Complete product user manual",
      "type": "pdf",
      "type_label": "PDF",
      "status": "active",
      "status_label": "Active",
      "created_at": "2025-01-05T10:30:00.000000Z",
      "updated_at": "2025-01-05T10:35:00.000000Z"
    }
  }
  ```

  ```json 404 Knowledgebase Not Found theme={null}
  {
    "error": "Knowledgebase not found."
  }
  ```

  ```json 404 Document Not Found theme={null}
  {
    "error": "Document not found."
  }
  ```
</ResponseExample>


# Get documents
Source: https://docs.autocalls.ai/api-reference/knowledgebases/get-documents

GET /user/knowledgebases/{knowledgebaseId}/documents
Get all documents in a knowledgebase

This endpoint returns a list of all documents in a specific knowledgebase.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the knowledgebase
</ParamField>

### Response

<ResponseField name="data" type="array">
  Array of document objects

  <Expandable title="document properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the document
    </ResponseField>

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

    <ResponseField name="description" type="string">
      Optional description of the document
    </ResponseField>

    <ResponseField name="type" type="string">
      Document type: `website`, `pdf`, `txt`, or `docx`
    </ResponseField>

    <ResponseField name="type_label" type="string">
      Human-readable type label
    </ResponseField>

    <ResponseField name="status" type="string">
      Processing status: `processing`, `active`, or `failed`
    </ResponseField>

    <ResponseField name="status_label" type="string">
      Human-readable status label
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": [
      {
        "id": 1,
        "name": "Product Manual",
        "description": "Complete product user manual",
        "type": "pdf",
        "type_label": "PDF",
        "status": "active",
        "status_label": "Active",
        "created_at": "2025-01-05T10:30:00.000000Z",
        "updated_at": "2025-01-05T10:35:00.000000Z"
      },
      {
        "id": 2,
        "name": "Company Website",
        "description": "Main website content",
        "type": "website",
        "type_label": "Website",
        "status": "processing",
        "status_label": "Processing",
        "created_at": "2025-01-08T09:00:00.000000Z",
        "updated_at": "2025-01-08T09:00:00.000000Z"
      }
    ]
  }
  ```

  ```json 404 Knowledgebase Not Found theme={null}
  {
    "error": "Knowledgebase not found."
  }
  ```
</ResponseExample>

### Document Statuses

| Status       | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `processing` | Document is being parsed and embedded into the vector database |
| `active`     | Document has been processed and is ready for use               |
| `failed`     | Document processing failed                                     |


# Get knowledgebase
Source: https://docs.autocalls.ai/api-reference/knowledgebases/get-knowledgebase

GET /user/knowledgebases/{id}
Get a single knowledgebase by ID

This endpoint returns the details of a specific knowledgebase.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the knowledgebase
</ParamField>

### Response

<ResponseField name="data" type="object">
  The knowledgebase object

  <Expandable title="knowledgebase properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the knowledgebase
    </ResponseField>

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

    <ResponseField name="description" type="string">
      Optional description of the knowledgebase
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status: `empty`, `processing`, `active`, or `failed`
    </ResponseField>

    <ResponseField name="status_label" type="string">
      Human-readable status label
    </ResponseField>

    <ResponseField name="documents_count" type="integer">
      Number of documents in this knowledgebase
    </ResponseField>

    <ResponseField name="assistants_count" type="integer">
      Number of assistants using this knowledgebase
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": {
      "id": 1,
      "name": "Product Documentation",
      "description": "Technical documentation for our products",
      "status": "active",
      "status_label": "Active",
      "documents_count": 5,
      "assistants_count": 2,
      "created_at": "2025-01-05T10:30:00.000000Z",
      "updated_at": "2025-01-08T14:20:00.000000Z"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Knowledgebase not found."
  }
  ```
</ResponseExample>


# Get knowledgebases
Source: https://docs.autocalls.ai/api-reference/knowledgebases/get-knowledgebases

GET /user/knowledgebases
Get all knowledgebases for the authenticated user

This endpoint returns a list of all knowledgebases associated with your account. Knowledgebases are used to store documents that provide context and information to your AI assistants.

### Response

<ResponseField name="data" type="array">
  Array of knowledgebase objects

  <Expandable title="knowledgebase properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the knowledgebase
    </ResponseField>

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

    <ResponseField name="description" type="string">
      Optional description of the knowledgebase
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status: `empty`, `processing`, `active`, or `failed`
    </ResponseField>

    <ResponseField name="status_label" type="string">
      Human-readable status label
    </ResponseField>

    <ResponseField name="documents_count" type="integer">
      Number of documents in this knowledgebase
    </ResponseField>

    <ResponseField name="assistants_count" type="integer">
      Number of assistants using this knowledgebase
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": [
      {
        "id": 1,
        "name": "Product Documentation",
        "description": "Technical documentation for our products",
        "status": "active",
        "status_label": "Active",
        "documents_count": 5,
        "assistants_count": 2,
        "created_at": "2025-01-05T10:30:00.000000Z",
        "updated_at": "2025-01-08T14:20:00.000000Z"
      },
      {
        "id": 2,
        "name": "FAQ Knowledge",
        "description": "Frequently asked questions and answers",
        "status": "processing",
        "status_label": "Processing",
        "documents_count": 1,
        "assistants_count": 0,
        "created_at": "2025-01-08T09:00:00.000000Z",
        "updated_at": "2025-01-08T09:05:00.000000Z"
      }
    ]
  }
  ```

  ```json 200 Empty Response theme={null}
  {
    "data": []
  }
  ```
</ResponseExample>

### Knowledgebase Statuses

| Status       | Description                               |
| ------------ | ----------------------------------------- |
| `empty`      | Knowledgebase has no documents            |
| `processing` | One or more documents are being processed |
| `active`     | All documents are processed and ready     |
| `failed`     | One or more documents failed to process   |


# Update document
Source: https://docs.autocalls.ai/api-reference/knowledgebases/update-document

PUT /user/knowledgebases/{knowledgebaseId}/documents/{documentId}
Update a document's name or description

This endpoint updates the metadata of an existing document. You can only update the name and description - the document type and content cannot be changed.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the knowledgebase
</ParamField>

<ParamField type="integer">
  The unique identifier of the document to update
</ParamField>

### Request Body

<ParamField type="string">
  The new name for the document (max 255 characters)
</ParamField>

<ParamField type="string">
  The new description for the document (max 255 characters)
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  The updated document object

  <Expandable title="data properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the document
    </ResponseField>

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

    <ResponseField name="description" type="string">
      Description of the document
    </ResponseField>

    <ResponseField name="type" type="string">
      Document type
    </ResponseField>

    <ResponseField name="type_label" type="string">
      Human-readable type label
    </ResponseField>

    <ResponseField name="status" type="string">
      Processing status
    </ResponseField>

    <ResponseField name="status_label" type="string">
      Human-readable status label
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "message": "Document updated successfully.",
    "data": {
      "id": 1,
      "name": "Updated Product Manual",
      "description": "Revised user guide with new features",
      "type": "pdf",
      "type_label": "PDF",
      "status": "active",
      "status_label": "Active",
      "updated_at": "2025-01-08T15:45:00.000000Z"
    }
  }
  ```

  ```json 404 Knowledgebase Not Found theme={null}
  {
    "error": "Knowledgebase not found."
  }
  ```

  ```json 404 Document Not Found theme={null}
  {
    "error": "Document not found."
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The name may not be greater than 255 characters.",
    "errors": {
      "name": [
        "The name may not be greater than 255 characters."
      ]
    }
  }
  ```
</ResponseExample>

<Note>
  To update the content of a document, you need to delete the existing document and create a new one with the updated content.
</Note>


# Update knowledgebase
Source: https://docs.autocalls.ai/api-reference/knowledgebases/update-knowledgebase

PUT /user/knowledgebases/{id}
Update an existing knowledgebase

This endpoint updates the name and/or description of an existing knowledgebase.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the knowledgebase to update
</ParamField>

### Request Body

<ParamField type="string">
  The new name for the knowledgebase (max 255 characters)
</ParamField>

<ParamField type="string">
  The new description for the knowledgebase (max 255 characters)
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  The updated knowledgebase object

  <Expandable title="data properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the knowledgebase
    </ResponseField>

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

    <ResponseField name="description" type="string">
      Description of the knowledgebase
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status
    </ResponseField>

    <ResponseField name="status_label" type="string">
      Human-readable status label
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "message": "Knowledgebase updated successfully.",
    "data": {
      "id": 1,
      "name": "Updated Product Documentation",
      "description": "Updated description for our technical docs",
      "status": "active",
      "status_label": "Active",
      "updated_at": "2025-01-08T15:45:00.000000Z"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Knowledgebase not found."
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The name may not be greater than 255 characters.",
    "errors": {
      "name": [
        "The name may not be greater than 255 characters."
      ]
    }
  }
  ```
</ResponseExample>

<Note>
  Updating a knowledgebase's name or description does not affect its documents or processing status.
</Note>


# Create label
Source: https://docs.autocalls.ai/api-reference/labels/create-label

POST /user/label
Create a label to tag your assistants

Create a label to tag assistants across folders (for example, `inbound` or `outbound`). Apply labels to assistants with the `label_ids` field on the [Create assistant](/api-reference/assistants/create-assistant) and [Update assistant](/api-reference/assistants/update-assistant) endpoints.

### Request Body

<ParamField type="string">
  The label name (max 255 characters). Must be unique within your account.
</ParamField>

<ParamField type="string">
  A color for the label badge. One of: `gray`, `slate`, `red`, `orange`, `amber`, `green`, `teal`, `blue`, `purple`, `pink`.
</ParamField>

### Response

<ResponseField name="message" type="string">Success message</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">The unique identifier of the created label</ResponseField>
    <ResponseField name="name" type="string">The label name</ResponseField>
    <ResponseField name="color" type="string">The label color (or `null`)</ResponseField>
    <ResponseField name="assistants_count" type="integer">Number of assistants this label is applied to (always `0` for a new label)</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Success Response theme={null}
  {
    "message": "Label created successfully",
    "data": { "id": 3, "name": "Inbound", "color": "green", "assistants_count": 0 }
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The name has already been taken.",
    "errors": { "name": ["The name has already been taken."] }
  }
  ```
</ResponseExample>


# Delete label
Source: https://docs.autocalls.ai/api-reference/labels/delete-label

DELETE /user/label/{id}
Delete a label

Delete a label. The label is removed from any assistants it was applied to — the assistants themselves are **not** affected.

### Path Parameters

<ParamField type="integer">
  The label ID. Must belong to your account.
</ParamField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  { "message": "Label deleted successfully" }
  ```

  ```json 404 Not Found theme={null}
  { "message": "Label not found" }
  ```
</ResponseExample>


# List labels
Source: https://docs.autocalls.ai/api-reference/labels/get-labels

GET /user/labels
List the labels in your account

Labels are tags you can apply to assistants. Unlike folders, an assistant can have multiple labels, and a label can be applied to many assistants. Labels are private to your account.

This endpoint returns your labels (paginated), each with the number of assistants it is applied to.

### Query Parameters

<ParamField type="integer">
  Number of labels per page (1-100, default: 15)
</ParamField>

<ParamField type="integer">
  Page number (default: 1)
</ParamField>

### Response fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">The unique identifier of the label</ResponseField>
    <ResponseField name="name" type="string">The label name</ResponseField>
    <ResponseField name="color" type="string">The label color (or `null`)</ResponseField>
    <ResponseField name="assistants_count" type="integer">Number of assistants this label is applied to</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "data": [
      { "id": 3, "name": "Inbound", "color": "green", "assistants_count": 7 },
      { "id": 5, "name": "Outbound", "color": "blue", "assistants_count": 2 }
    ],
    "current_page": 1,
    "per_page": 15,
    "total": 2
  }
  ```
</ResponseExample>


# Update label
Source: https://docs.autocalls.ai/api-reference/labels/update-label

PUT /user/label/{id}
Rename a label or change its color

Update a label's name or color. Only the fields you send are changed.

### Path Parameters

<ParamField type="integer">
  The label ID. Must belong to your account.
</ParamField>

### Request Body

<ParamField type="string">
  New name (max 255 characters). Must be unique within your account.
</ParamField>

<ParamField type="string">
  New color. One of: `gray`, `slate`, `red`, `orange`, `amber`, `green`, `teal`, `blue`, `purple`, `pink`. Send `null` to clear it.
</ParamField>

### Response

<ResponseField name="message" type="string">Success message</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">The label ID</ResponseField>
    <ResponseField name="name" type="string">The label name</ResponseField>
    <ResponseField name="color" type="string">The label color (or `null`)</ResponseField>
    <ResponseField name="assistants_count" type="integer">Number of assistants this label is applied to</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "message": "Label updated successfully",
    "data": { "id": 3, "name": "Inbound calls", "color": "teal", "assistants_count": 7 }
  }
  ```

  ```json 404 Not Found theme={null}
  { "message": "Label not found" }
  ```
</ResponseExample>


# Create lead
Source: https://docs.autocalls.ai/api-reference/leads/create

POST /user/lead
Create a new lead in the Autocalls system

This endpoint allows you to create a new lead in the Autocalls system.

### Request body

<ParamField type="string">
  The phone number of the lead in E.164 format (e.g. +1234567890)
</ParamField>

<ParamField type="integer">
  The ID of the campaign to create the lead for
</ParamField>

<ParamField type="object">
  Custom variables for the lead. For **call** campaigns, use variables defined on your assistant (see [Call variables](/ai-assistants/settings/prompt-and-tools#call-variables)). For **WhatsApp/SMS** campaigns, use the keys referenced by your template mapping or SMS body placeholders.

  <Expandable title="Example variables (add your own)">
    <ParamField type="string">
      e.g. the name of the customer
    </ParamField>

    <ParamField type="string">
      e.g. the email of the customer
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="boolean">
  Whether to allow duplicate leads in a campaign.
</ParamField>

<ParamField type="array">
  Call campaigns only. Extra phone numbers for the same lead. Rejected for WhatsApp/SMS campaigns.

  <Expandable title="secondary_contacts properties">
    <ParamField type="string">
      The phone number of the secondary contact in E.164 format
    </ParamField>

    <ParamField type="object">
      The variables to pass to the secondary contact

      <Expandable title="variables properties">
        <ParamField type="string">
          The name of the secondary contact
        </ParamField>

        <ParamField type="string">
          The email of the secondary contact
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="message" type="string">
  The message of the response
</ResponseField>

<ResponseField name="data" type="object">
  The lead data object

  <Expandable title="data properties">
    <ResponseField name="id" type="integer">
      The unique ID of the created lead
    </ResponseField>

    <ResponseField name="campaign_id" type="integer">
      The ID of the campaign this lead belongs to
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The phone number of the lead in E.164 format
    </ResponseField>

    <ResponseField name="variables" type="object">
      The variables associated with the lead

      <Expandable title="variables properties">
        <ResponseField name="customer_name" type="string">
          The name of the customer
        </ResponseField>

        <ResponseField name="email" type="string">
          The email of the customer
        </ResponseField>
      </Expandable>
    </ResponseField>

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

    <ResponseField name="created_at" type="string">
      The timestamp when the lead was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      The timestamp when the lead was last updated
    </ResponseField>

    <ResponseField name="campaign" type="object">
      The campaign information

      <Expandable title="campaign properties">
        <ResponseField name="id" type="integer">
          The id of the campaign
        </ResponseField>

        <ResponseField name="name" type="string">
          The name of the campaign
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="secondary_contacts" type="array">
      Array of secondary contact leads associated with this lead

      <Expandable title="secondary_contacts properties">
        <ResponseField name="id" type="integer">
          The id of the secondary contact lead
        </ResponseField>

        <ResponseField name="phone_number" type="string">
          The phone number of the secondary contact in E.164 format
        </ResponseField>

        <ResponseField name="variables" type="object">
          The variables associated with the secondary contact
        </ResponseField>

        <ResponseField name="status" type="string">
          The status of the secondary contact
        </ResponseField>

        <ResponseField name="created_at" type="string">
          The created at date of the secondary contact
        </ResponseField>

        <ResponseField name="updated_at" type="string">
          The updated at date of the secondary contact
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "message": "Lead created successfully",
    "data": {
      "id": 1,
      "campaign_id": 1,
      "phone_number": "+1234567890",
      "variables": {
        "customer_name": "John Doe",
        "email": "john.doe@example.com"
      },
      "status": "created",
      "created_at": "2025-06-30 11:53:20",
      "updated_at": "2025-06-30 11:53:20",
      "campaign": {
        "id": 1,
        "name": "My new campaign"
      },
      "secondary_contacts": [
        {
          "id": 2,
          "phone_number": "+1234567891",
          "variables": {
            "customer_name": "Jane Doe Secondary",
            "email": "jane.doe.secondary@example.com"
          },
          "status": "created",
          "created_at": "2025-06-30 11:53:20",
          "updated_at": "2025-06-30 11:53:20"
        },
        {
          "id": 3,
          "phone_number": "+1234567892",
          "variables": {
            "customer_name": "Bob Doe Office",
            "email": "bob.doe.office@example.com"
          },
          "status": "created",
          "created_at": "2025-06-30 11:53:20",
          "updated_at": "2025-06-30 11:53:20"
        }
      ]
    }
  }
  ```
</ResponseExample>


# Delete lead
Source: https://docs.autocalls.ai/api-reference/leads/delete

DELETE /user/leads/{id}
Delete a lead from the Autocalls system

This endpoint allows you to delete a lead from the Autocalls system.

### Path Parameters

<ParamField type="integer">
  The ID of the lead to delete
</ParamField>

### Response

<ResponseField name="message" type="string">
  The message of the response
</ResponseField>


# List leads
Source: https://docs.autocalls.ai/api-reference/leads/get-lead

GET /user/leads
List all leads for the authenticated user with filtering and pagination options

This endpoint allows you to list all leads belonging to the authenticated user with various filtering and pagination options.

### Query Parameters

<ParamField type="string">
  Filter leads by status. Possible values: `created`, `scheduled`, `processing`, `completed`, `rescheduled`, `reached-max-retries`, `blacklisted`
</ParamField>

<ParamField type="integer">
  Filter leads by campaign ID
</ParamField>

<ParamField type="string">
  Filter leads by phone number (partial match supported)
</ParamField>

<ParamField type="string">
  Filter leads created from this date (YYYY-MM-DD format)
</ParamField>

<ParamField type="string">
  Filter leads created until this date (YYYY-MM-DD format)
</ParamField>

<ParamField type="integer">
  Number of leads per page (1-100, default: 15)
</ParamField>

<ParamField type="integer">
  Page number (default: 1)
</ParamField>

### Response fields

<ResponseField name="data" type="array">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The id of the lead
    </ResponseField>

    <ResponseField name="campaign_id" type="integer">
      The ID of the campaign this lead belongs to
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The phone number of the lead in E.164 format
    </ResponseField>

    <ResponseField name="variables" type="object">
      The variables associated with the lead
    </ResponseField>

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

    <ResponseField name="fallback_sent_at" type="string">
      When a call→text fallback was sent for this lead, or `null`
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The created at date of the lead
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      The updated at date of the lead
    </ResponseField>

    <ResponseField name="campaign" type="object">
      The campaign information

      <Expandable title="campaign properties">
        <ResponseField name="id" type="integer">
          The id of the campaign
        </ResponseField>

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

        <ResponseField name="channel" type="string">
          `call`, `whatsapp`, or `sms`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="secondary_contacts" type="array">
      Array of secondary contact leads associated with this lead

      <Expandable title="secondary_contacts properties">
        <ResponseField name="id" type="integer">
          The id of the secondary contact lead
        </ResponseField>

        <ResponseField name="phone_number" type="string">
          The phone number of the secondary contact in E.164 format
        </ResponseField>

        <ResponseField name="variables" type="object">
          The variables associated with the secondary contact
        </ResponseField>

        <ResponseField name="status" type="string">
          The status of the secondary contact
        </ResponseField>

        <ResponseField name="created_at" type="string">
          The created at date of the secondary contact
        </ResponseField>

        <ResponseField name="updated_at" type="string">
          The updated at date of the secondary contact
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="current_page" type="integer">
  The current page number
</ResponseField>

<ResponseField name="per_page" type="integer">
  Number of items per page
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of leads matching the criteria
</ResponseField>

<ResponseField name="last_page" type="integer">
  The last page number
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "current_page": 1,
    "data": [
      {
        "id": 1,
        "campaign_id": 1,
        "phone_number": "+1234567890",
        "variables": {
          "customer_name": "John Doe",
          "email": "john.doe@example.com"
        },
        "status": "created",
        "fallback_sent_at": null,
        "created_at": "2025-06-30 11:18:04",
        "updated_at": "2025-06-30 11:18:04",
        "campaign": {
          "id": 1,
          "name": "My new campaign",
          "channel": "call"
        },
        "secondary_contacts": [
          {
            "id": 2,
            "phone_number": "+1234567899",
            "variables": {
              "customer_name": "Jane Doe Secondary",
              "email": "jane.doe.secondary@example.com"
            },
            "status": "created",
            "created_at": "2025-06-30 11:18:04",
            "updated_at": "2025-06-30 11:18:04"
          }
        ]
      }
    ],
    "first_page_url": "https://app.autocalls.ai/api/user/leads?page=1",
    "from": 1,
    "last_page": 10,
    "last_page_url": "https://app.autocalls.ai/api/user/leads?page=10",
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://app.autocalls.ai/api/user/leads?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://app.autocalls.ai/api/user/leads?page=2",
        "label": "2",
        "active": false
      }
    ],
    "next_page_url": "https://app.autocalls.ai/api/user/leads?page=2",
    "path": "https://app.autocalls.ai/api/user/leads",
    "per_page": 15,
    "prev_page_url": null,
    "to": 15,
    "total": 150
  }
  ```
</ResponseExample>


# Update Lead
Source: https://docs.autocalls.ai/api-reference/leads/update-lead

PUT /user/leads/{id}
Update an existing lead in your campaigns

Update a lead by providing the lead ID and the fields you want to modify. Only the fields provided in the request will be updated.

## Path Parameters

<ParamField type="integer">
  The ID of the lead to update
</ParamField>

## Body Parameters

<ParamField type="integer">
  The ID of the campaign to assign the lead to
</ParamField>

<ParamField type="string">
  The phone number of the lead (will be formatted to E164)
</ParamField>

<ParamField type="string">
  The status of the lead. Must be one of: `created`, `completed`, `reached-max-retries`
</ParamField>

<ParamField type="object">
  Custom variables to merge with existing lead variables
</ParamField>

## Response

<ResponseField name="message" type="string">
  Success message indicating the lead was updated
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://app.autocalls.ai/api/user/leads/123" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "campaign_id": 456,
      "phone_number": "+1234567890",
      "variables": {
        "name": "John Doe",
        "company": "Acme Corp"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "message": "Lead updated successfully"
  }
  ```

  ```json Error Response - Lead Not Found theme={null}
  {
    "message": "Lead not found"
  }
  ```

  ```json Error Response - Campaign Not Found theme={null}
  {
    "message": "Campaign not found"
  }
  ```

  ```json Error Response - Invalid Phone Number theme={null}
  {
    "message": "Invalid phone number"
  }
  ```

  ```json Error Response - Validation Failed theme={null}
  {
    "message": "Validation failed",
    "errors": {
      "campaign_id": ["The selected campaign does not exist"],
      "status": ["This status is assigned automatically and cannot be set manually"],
      "variables": ["Variables must be an array"]
    }
  }
  ```

  ```json Error Response - Invalid Fields theme={null}
  {
    "message": "Invalid fields: invalid_field, another_invalid_field"
  }
  ```
</ResponseExample>

## Notes

* The lead must belong to the authenticated user
* If updating the campaign, the new campaign must also belong to the authenticated user
* Phone numbers are automatically formatted and validated
* Variables are merged with existing variables (not replaced)
* Only allowed fields can be updated: `campaign_id`, `phone_number`, `status`, `variables`
* The `status` field has restricted values for data integrity


# Create mid call tool
Source: https://docs.autocalls.ai/api-reference/mid-call-tools/create-tool

POST /user/tools
Create a new mid call tool

This endpoint allows you to create a new mid call tool that can be used by your AI assistants to interact with external APIs during calls.

### Body Parameters

<Info>
  The public API creates **HTTP request** tools. Automation Platform tools (which
  generate a linked flow) are created from the dashboard. Tool values support
  dynamic variables — use `{param}` for AI-extracted parameters in the URL, and
  `{{variable}}` (e.g. `{{customer_phone}}`) in the URL, header values, and static
  field values.
</Info>

<ParamField type="string">
  Tool name — letters, numbers and underscores, starting with a letter or underscore (max 64 characters, e.g., `get_weather`, `book_appointment`)
</ParamField>

<ParamField type="string">
  Detailed explanation of when and how the AI should use this tool (max 255 characters)
</ParamField>

<ParamField type="string">
  Valid URL of the API endpoint to call (max 2048 characters)
</ParamField>

<ParamField type="string">
  HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`
</ParamField>

<ParamField type="string">
  How the request body is encoded for write methods (POST/PUT/PATCH): `json` (default) or `form` (`application/x-www-form-urlencoded`)
</ParamField>

<ParamField type="integer">
  Request timeout in seconds (1-30, default: 10)
</ParamField>

<ParamField type="array">
  HTTP headers to send with the request

  <Expandable title="headers properties">
    <ParamField type="string">
      Header name
    </ParamField>

    <ParamField type="string">
      Header value (max 2048 chars; supports `{{variable}}` substitution)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="array">
  Fixed key/value pairs always sent with the request (the AI never changes them)

  <Expandable title="static_fields properties">
    <ParamField type="string">
      Field key (max 64 chars)
    </ParamField>

    <ParamField type="string">
      Field value (max 2048 chars; supports `{{variable}}` substitution)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="array">
  Parameters that the AI will extract from conversation and send to the endpoint

  <Expandable title="schema properties">
    <ParamField type="string">
      Parameter name (1-64 chars, must start with a letter or underscore, can contain letters, numbers and underscores)
    </ParamField>

    <ParamField type="string">
      Parameter type: `string`, `number`, `float`, or `boolean`
    </ParamField>

    <ParamField type="string">
      Description to help AI understand how to extract this parameter (3-255 chars)
    </ParamField>

    <ParamField type="boolean">
      Whether the AI must collect this parameter. Optional parameters are only sent when a value was collected. Defaults to `false`.
    </ParamField>
  </Expandable>
</ParamField>

### Response fields

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  The created tool object

  <Expandable title="data properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the tool
    </ResponseField>

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

    <ResponseField name="description" type="string">
      Tool description
    </ResponseField>

    <ResponseField name="type" type="string">
      Tool type: `http` or `automation`
    </ResponseField>

    <ResponseField name="endpoint" type="string">
      API endpoint URL
    </ResponseField>

    <ResponseField name="method" type="string">
      HTTP method
    </ResponseField>

    <ResponseField name="body_format" type="string">
      Request body encoding: `json` or `form`
    </ResponseField>

    <ResponseField name="timeout" type="integer">
      Request timeout in seconds
    </ResponseField>

    <ResponseField name="headers" type="array">
      HTTP headers
    </ResponseField>

    <ResponseField name="static_fields" type="array">
      Fixed key/value pairs always sent with the request
    </ResponseField>

    <ResponseField name="schema" type="array">
      Parameter schema
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "message": "Tool created successfully",
    "data": {
      "id": 1,
      "name": "check_order_status",
      "description": "Use this tool to check the status of a customer's order.",
      "type": "http",
      "endpoint": "https://api.yourstore.com/orders/{order_id}/status",
      "method": "GET",
      "body_format": "json",
      "timeout": 10,
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Authorization",
          "value": "Bearer {{crm_key}}"
        }
      ],
      "static_fields": [
        {
          "key": "source",
          "value": "autocalls"
        },
        {
          "key": "caller",
          "value": "{{customer_phone}}"
        }
      ],
      "schema": [
        {
          "name": "order_id",
          "type": "string",
          "description": "The customer's order ID",
          "required": true
        },
        {
          "name": "amount",
          "type": "float",
          "description": "Order total as a decimal, e.g. 19.99",
          "required": false
        },
        {
          "name": "priority_order",
          "type": "boolean",
          "description": "Whether this is a priority order",
          "required": false
        }
      ],
      "created_at": "2025-10-10T12:00:00.000000Z",
      "updated_at": "2025-10-10T12:00:00.000000Z"
    }
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "Tool name must start with a letter or underscore and contain only letters, numbers, and underscores (max 64 characters).",
    "errors": {
      "name": [
        "Tool name must start with a letter or underscore and contain only letters, numbers, and underscores (max 64 characters)."
      ]
    }
  }
  ```

  ```json 422 Plan Limit Reached theme={null}
  {
    "message": "You have reached your plan limit of 5 mid call tools. Please upgrade your plan to create more tools."
  }
  ```
</ResponseExample>

### Attaching Tools to Assistants

After creating a tool, you need to attach it to an assistant to use it during calls. Tools are managed through the Assistant API:

* **[Create Assistant](/api-reference/assistants/create-assistant)** - Use the `tool_ids` parameter to attach tools when creating an assistant
* **[Update Assistant](/api-reference/assistants/update-assistant)** - Use the `tool_ids` parameter to add, remove, or replace tools on an existing assistant


# Delete mid call tool
Source: https://docs.autocalls.ai/api-reference/mid-call-tools/delete-tool

DELETE /user/tools/{id}
Delete a mid call tool

This endpoint allows you to permanently delete a mid call tool. This will also remove the tool from all assistants it was assigned to.

### Headers

<ParamField type="string">
  Bearer token for authentication
</ParamField>

<ParamField type="string">
  Must be `application/json`
</ParamField>

<ParamField type="string">
  Must be `application/json`
</ParamField>

### Path Parameters

<ParamField type="integer">
  The unique identifier of the tool to delete
</ParamField>

### Response fields

<ResponseField name="message" type="string">
  Success message confirming deletion
</ResponseField>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "Tool deleted successfully"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Tool not found"
  }
  ```
</ResponseExample>

### Note

When a tool is deleted, it is automatically removed from all assistants. To manage tool assignments without deleting the tool, use:

* **[Update Assistant](/api-reference/assistants/update-assistant)** - Use the `tool_ids` parameter to remove tools from specific assistants


# Get mid call tool
Source: https://docs.autocalls.ai/api-reference/mid-call-tools/get-tool

GET /user/tools/{id}
Retrieve a specific mid call tool by ID

This endpoint allows you to retrieve detailed information about a specific mid call tool.

### Headers

<ParamField type="string">
  Bearer token for authentication
</ParamField>

<ParamField type="string">
  Must be `application/json`
</ParamField>

<ParamField type="string">
  Must be `application/json`
</ParamField>

### Path Parameters

<ParamField type="integer">
  The unique identifier of the tool
</ParamField>

### Response fields

<ResponseField name="id" type="integer">
  The unique identifier of the tool
</ResponseField>

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

<ResponseField name="description" type="string">
  Detailed explanation of when and how the AI should use this tool
</ResponseField>

<ResponseField name="type" type="string">
  Tool type: `http` or `automation`
</ResponseField>

<ResponseField name="endpoint" type="string">
  The API endpoint URL that will be called
</ResponseField>

<ResponseField name="method" type="string">
  HTTP method (GET, POST, PUT, PATCH, DELETE)
</ResponseField>

<ResponseField name="body_format" type="string">
  Request body encoding: `json` or `form`
</ResponseField>

<ResponseField name="timeout" type="integer">
  Request timeout in seconds (1-30)
</ResponseField>

<ResponseField name="headers" type="array">
  HTTP headers to send with the request

  <Expandable title="header properties">
    <ResponseField name="name" type="string">
      Header name
    </ResponseField>

    <ResponseField name="value" type="string">
      Header value
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="static_fields" type="array">
  Fixed key/value pairs always sent with the request

  <Expandable title="static_fields properties">
    <ResponseField name="key" type="string">
      Field key
    </ResponseField>

    <ResponseField name="value" type="string">
      Field value
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="schema" type="array">
  Parameters that the AI will extract and send to the endpoint

  <Expandable title="schema properties">
    <ResponseField name="name" type="string">
      Parameter name
    </ResponseField>

    <ResponseField name="type" type="string">
      Parameter type (string, number, float, boolean)
    </ResponseField>

    <ResponseField name="description" type="string">
      Description to help AI understand how to extract this parameter
    </ResponseField>

    <ResponseField name="required" type="boolean">
      Whether the AI must collect this parameter
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the tool was created
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp when the tool was last updated
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "id": 1,
    "name": "get_weather",
    "description": "Use this tool to get the current weather in a specific city. Call this when the customer asks about weather conditions.",
    "type": "http",
    "endpoint": "https://api.openweathermap.org/data/2.5/weather?city={city}",
    "method": "GET",
    "body_format": "json",
    "timeout": 10,
    "headers": [
      {
        "name": "Content-Type",
        "value": "application/json"
      },
      {
        "name": "Authorization",
        "value": "Bearer sk_..."
      }
    ],
    "static_fields": [
      {
        "key": "source",
        "value": "autocalls"
      }
    ],
    "schema": [
      {
        "name": "city",
        "type": "string",
        "description": "The city name to get weather for",
        "required": true
      },
      {
        "name": "days",
        "type": "number",
        "description": "Number of forecast days",
        "required": false
      }
    ],
    "created_at": "2025-10-10T12:00:00.000000Z",
    "updated_at": "2025-10-10T12:00:00.000000Z"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Tool not found"
  }
  ```
</ResponseExample>

### Assigning Tools to Assistants

To use this tool with an assistant, see:

* **[Create Assistant](/api-reference/assistants/create-assistant)** - Attach tools using the `tool_ids` parameter
* **[Update Assistant](/api-reference/assistants/update-assistant)** - Manage tool assignments using the `tool_ids` parameter


# List mid call tools
Source: https://docs.autocalls.ai/api-reference/mid-call-tools/get-tools

GET /user/tools
Retrieve all mid call tools

This endpoint allows you to retrieve all mid call tools. Mid call tools enable your AI assistants to interact with external APIs during a call.

### Headers

<ParamField type="string">
  Bearer token for authentication
</ParamField>

<ParamField type="string">
  Must be `application/json`
</ParamField>

<ParamField type="string">
  Must be `application/json`
</ParamField>

### Response fields

<ResponseField name="data" type="array">
  Array of mid call tools

  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the tool
    </ResponseField>

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

    <ResponseField name="description" type="string">
      Detailed explanation of when and how the AI should use this tool
    </ResponseField>

    <ResponseField name="type" type="string">
      Tool type: `http` or `automation`
    </ResponseField>

    <ResponseField name="endpoint" type="string">
      The API endpoint URL that will be called
    </ResponseField>

    <ResponseField name="method" type="string">
      HTTP method (GET, POST, PUT, PATCH, DELETE)
    </ResponseField>

    <ResponseField name="body_format" type="string">
      Request body encoding: `json` or `form`
    </ResponseField>

    <ResponseField name="timeout" type="integer">
      Request timeout in seconds (1-30)
    </ResponseField>

    <ResponseField name="headers" type="array">
      HTTP headers to send with the request

      <Expandable title="header properties">
        <ResponseField name="name" type="string">
          Header name
        </ResponseField>

        <ResponseField name="value" type="string">
          Header value
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="static_fields" type="array">
      Fixed key/value pairs always sent with the request

      <Expandable title="static_fields properties">
        <ResponseField name="key" type="string">
          Field key
        </ResponseField>

        <ResponseField name="value" type="string">
          Field value
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="schema" type="array">
      Parameters that the AI will extract and send to the endpoint

      <Expandable title="schema properties">
        <ResponseField name="name" type="string">
          Parameter name
        </ResponseField>

        <ResponseField name="type" type="string">
          Parameter type (string, number, float, boolean)
        </ResponseField>

        <ResponseField name="description" type="string">
          Description to help AI understand how to extract this parameter
        </ResponseField>

        <ResponseField name="required" type="boolean">
          Whether the AI must collect this parameter
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp when the tool was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp when the tool was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  [
    {
      "id": 1,
      "name": "get_weather",
      "description": "Use this tool to get the current weather in a specific city. Call this when the customer asks about weather conditions.",
      "type": "http",
      "endpoint": "https://api.openweathermap.org/data/2.5/weather?city={city}",
      "method": "GET",
      "body_format": "json",
      "timeout": 10,
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Authorization",
          "value": "Bearer sk_..."
        }
      ],
      "static_fields": [],
      "schema": [
        {
          "name": "city",
          "type": "string",
          "description": "The city name to get weather for",
          "required": true
        },
        {
          "name": "days",
          "type": "number",
          "description": "Number of forecast days",
          "required": false
        }
      ],
      "created_at": "2025-10-10T12:00:00.000000Z",
      "updated_at": "2025-10-10T12:00:00.000000Z"
    },
    {
      "id": 2,
      "name": "send_notification",
      "description": "Use this tool to send a notification to the customer. Call this when customer requests updates.",
      "type": "http",
      "endpoint": "https://api.yourcompany.com/notifications/send",
      "method": "POST",
      "body_format": "json",
      "timeout": 15,
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ],
      "static_fields": [
        {
          "key": "caller",
          "value": "{{customer_phone}}"
        }
      ],
      "schema": [
        {
          "name": "message",
          "type": "string",
          "description": "The notification message to send",
          "required": true
        },
        {
          "name": "send_sms",
          "type": "boolean",
          "description": "Whether to also send SMS notification",
          "required": false
        }
      ],
      "created_at": "2025-10-09T14:30:00.000000Z",
      "updated_at": "2025-10-10T09:15:00.000000Z"
    }
  ]
  ```
</ResponseExample>

### Assigning Tools to Assistants

To use these tools with assistants, see:

* **[Create Assistant](/api-reference/assistants/create-assistant)** - Attach tools using the `tool_ids` parameter
* **[Update Assistant](/api-reference/assistants/update-assistant)** - Manage tool assignments using the `tool_ids` parameter


# Update mid call tool
Source: https://docs.autocalls.ai/api-reference/mid-call-tools/update-tool

PUT /user/tools/{id}
Update an existing mid call tool

This endpoint allows you to update an existing mid call tool. All fields are optional - only provide the fields you want to update.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the tool to update
</ParamField>

### Body Parameters

<Note>
  For tools linked to an Automation Platform flow, the `endpoint`, `method`, and
  `body_format` fields are ignored to protect the flow connection.
</Note>

<ParamField type="string">
  Tool name — letters, numbers and underscores, starting with a letter or underscore (max 64 characters)
</ParamField>

<ParamField type="string">
  Detailed explanation of when and how the AI should use this tool (max 255 characters)
</ParamField>

<ParamField type="string">
  Valid URL of the API endpoint to call (max 2048 characters)
</ParamField>

<ParamField type="string">
  HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`
</ParamField>

<ParamField type="string">
  Request body encoding for write methods: `json` (default) or `form`
</ParamField>

<ParamField type="integer">
  Request timeout in seconds (1-30)
</ParamField>

<ParamField type="array">
  HTTP headers to send with the request (replaces existing headers)

  <Expandable title="headers properties">
    <ParamField type="string">
      Header name
    </ParamField>

    <ParamField type="string">
      Header value (supports `{{variable}}` substitution)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="array">
  Fixed key/value pairs always sent with the request (replaces existing static fields)

  <Expandable title="static_fields properties">
    <ParamField type="string">
      Field key (max 64 chars)
    </ParamField>

    <ParamField type="string">
      Field value (max 2048 chars; supports `{{variable}}` substitution)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="array">
  Parameters schema (replaces existing schema)

  <Expandable title="schema properties">
    <ParamField type="string">
      Parameter name (1-64 chars, starts with a letter or underscore)
    </ParamField>

    <ParamField type="string">
      Parameter type: `string`, `number`, `float`, or `boolean`
    </ParamField>

    <ParamField type="string">
      Parameter description (3-255 chars)
    </ParamField>

    <ParamField type="boolean">
      Whether the AI must collect this parameter (default `false`)
    </ParamField>
  </Expandable>
</ParamField>

### Response fields

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  The updated tool object with all current values
</ResponseField>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "Tool updated successfully",
    "data": {
      "id": 1,
      "name": "update_customer_info",
      "description": "Use this tool to update customer information in the system.",
      "type": "http",
      "endpoint": "https://api.yourcompany.com/customers/update",
      "method": "POST",
      "body_format": "json",
      "timeout": 15,
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ],
      "static_fields": [
        {
          "key": "source",
          "value": "autocalls"
        }
      ],
      "schema": [
        {
          "name": "customer_name",
          "type": "string",
          "description": "Full name of the customer",
          "required": true
        },
        {
          "name": "balance",
          "type": "float",
          "description": "Account balance as a decimal",
          "required": false
        },
        {
          "name": "newsletter_subscription",
          "type": "boolean",
          "description": "Whether customer wants to subscribe to newsletter",
          "required": false
        }
      ],
      "created_at": "2025-10-10T12:00:00.000000Z",
      "updated_at": "2025-10-10T14:30:00.000000Z"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Tool not found"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "Validation failed",
    "errors": {
      "name": ["Tool name must start with a letter or underscore and contain only letters, numbers, and underscores (max 64 characters)."]
    }
  }
  ```
</ResponseExample>

### Managing Tool Assignments

To attach or detach this tool from assistants, use the Assistant API:

* **[Create Assistant](/api-reference/assistants/create-assistant)** - Use the `tool_ids` parameter to attach tools when creating an assistant
* **[Update Assistant](/api-reference/assistants/update-assistant)** - Use the `tool_ids` parameter to manage which tools are assigned to an assistant


# Get all phone numbers
Source: https://docs.autocalls.ai/api-reference/phone-numbers/get-phone-numbers

GET /user/phone-numbers/all
Get all phone numbers owned by the authenticated user

This endpoint returns a list of all phone numbers associated with your account, including their subscription status and capabilities.

### Response

<ResponseField name="data" type="array">
  Array of phone number objects

  <Expandable title="phone number properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the phone number
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The phone number in E.164 format (e.g., +14155551234)
    </ResponseField>

    <ResponseField name="nickname" type="string">
      A short, human-friendly label for the number (or `null` if not set)
    </ResponseField>

    <ResponseField name="country_code" type="string">
      The ISO 3166-1 alpha-2 country code (e.g., US, GB, AU)
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of phone number: `normal`, `sip`, or `caller_id`
    </ResponseField>

    <ResponseField name="type_label" type="string">
      Human-readable label for the phone number type
    </ResponseField>

    <ResponseField name="sms_capable" type="boolean">
      Whether the phone number can send and receive SMS
    </ResponseField>

    <ResponseField name="region" type="string">
      The region where the phone number is provisioned
    </ResponseField>

    <ResponseField name="has_active_subscription" type="boolean">
      Whether the phone number has an active subscription
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the phone number was purchased
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": [
      {
        "id": 1,
        "phone_number": "+14155551234",
        "nickname": "Sales line",
        "country_code": "US",
        "type": "normal",
        "type_label": "Dedicated Number",
        "sms_capable": true,
        "region": "us1",
        "has_active_subscription": true,
        "created_at": "2025-01-08T10:30:00.000000Z"
      },
      {
        "id": 2,
        "phone_number": "+442071234567",
        "nickname": null,
        "country_code": "GB",
        "type": "normal",
        "type_label": "Dedicated Number",
        "sms_capable": false,
        "region": "us1",
        "has_active_subscription": true,
        "created_at": "2025-01-05T14:20:00.000000Z"
      }
    ]
  }
  ```
</ResponseExample>

<Note>
  There is also a legacy endpoint `GET /user/phone-numbers` that returns only SMS-capable phone numbers with active subscriptions. Use this `/all` endpoint if you need all phone numbers regardless of SMS capability or subscription status.
</Note>


# Purchase phone number
Source: https://docs.autocalls.ai/api-reference/phone-numbers/purchase-phone-number

POST /user/phone-numbers/purchase
Purchase a dedicated phone number

This endpoint allows you to purchase a phone number that was found using the [search endpoint](/api-reference/phone-numbers/search-phone-numbers). The platform automatically handles pricing, billing, and provisioning.

<Note>
  You must have a valid payment method on file before purchasing a phone number. The purchase creates a monthly subscription that will auto-renew.
</Note>

### Request Body

<ParamField type="string">
  The phone number to purchase in E.164 format (e.g., +14155551234). Must be a number returned from the search endpoint.
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  The purchased phone number details

  <Expandable title="data properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the phone number
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The phone number in E.164 format
    </ResponseField>

    <ResponseField name="country_code" type="string">
      The ISO country code
    </ResponseField>

    <ResponseField name="type" type="string">
      The phone number type (always `normal` for purchased numbers)
    </ResponseField>

    <ResponseField name="sms_capable" type="boolean">
      Whether the number supports SMS
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "message": "Phone number purchased successfully.",
    "data": {
      "id": 123,
      "phone_number": "+14155551234",
      "country_code": "US",
      "type": "normal",
      "sms_capable": true
    }
  }
  ```

  ```json 400 Already In Use theme={null}
  {
    "error": "This phone number is already in use."
  }
  ```

  ```json 400 Not Available theme={null}
  {
    "error": "This phone number is not available for purchase. Please search for available numbers first."
  }
  ```

  ```json 402 No Payment Method theme={null}
  {
    "error": "No payment method found. Please add a payment method to your account."
  }
  ```

  ```json 402 Payment Failed theme={null}
  {
    "error": "Payment failed. Please update your payment method."
  }
  ```

  ```json 422 Invalid Format theme={null}
  {
    "error": "Unable to parse phone number. Please provide a valid E.164 format number."
  }
  ```

  ```json 500 Provider Error theme={null}
  {
    "error": "Failed to purchase phone number from provider. Please contact support."
  }
  ```
</ResponseExample>

### How It Works

1. **Search** - First use the [search endpoint](/api-reference/phone-numbers/search-phone-numbers) to find available numbers
2. **Purchase** - Submit the phone number you want to this endpoint
3. **Automatic Processing** - The platform:
   * Validates the number is still available
   * Determines the correct pricing based on country
   * Creates a monthly subscription on your payment method
   * Provisions the number with our telephony provider
   * Creates the phone number record in your account

<Warning>
  Phone number purchases are non-refundable. The subscription will continue until you [release the number](/api-reference/phone-numbers/release-phone-number).
</Warning>


# Release phone number
Source: https://docs.autocalls.ai/api-reference/phone-numbers/release-phone-number

DELETE /user/phone-numbers/{id}
Release a phone number and cancel its subscription

This endpoint releases a phone number from your account. For dedicated numbers with subscriptions, this cancels the subscription and the number will be released at the end of the current billing period.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the phone number to release
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message indicating the release status
</ResponseField>

<ResponseExample>
  ```json 200 Subscription Cancelled theme={null}
  {
    "message": "Phone number released successfully. It will be removed at the end of the billing period."
  }
  ```

  ```json 200 Immediately Deleted theme={null}
  {
    "message": "Phone number deleted successfully."
  }
  ```

  ```json 400 Already Scheduled theme={null}
  {
    "error": "Phone number is already scheduled for release."
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Phone number not found."
  }
  ```

  ```json 500 Error theme={null}
  {
    "error": "Failed to release phone number. Please try again or contact support."
  }
  ```
</ResponseExample>

### Release Behavior

The release behavior depends on the phone number type:

| Type                   | Behavior                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------------- |
| **Dedicated (normal)** | Subscription is cancelled. Number remains active until the end of the billing period, then is released. |
| **SIP**                | Immediately deleted from your account.                                                                  |
| **Caller ID**          | Immediately deleted from your account and removed from the telephony provider.                          |

<Warning>
  Once a phone number is released, you may not be able to get the same number back. Make sure to update any assistants or campaigns using this number before releasing it.
</Warning>

### What Happens to Attached Resources

When you release a phone number:

* Any **inbound assistants** attached to this number will have their phone number unassigned
* Any **campaigns** using this number will have it removed from their phone number rotation
* **Call history** is preserved and remains accessible


# Search available phone numbers
Source: https://docs.autocalls.ai/api-reference/phone-numbers/search-phone-numbers

GET /user/phone-numbers/search
Search for available phone numbers that can be purchased

This endpoint allows you to search for available phone numbers from our provider. Use the results to find a number you want to purchase.

### Query Parameters

<ParamField type="string">
  The ISO 3166-1 alpha-2 country code to search in (e.g., US, GB, AU, CA)
</ParamField>

<ParamField type="string">
  Filter phone numbers that contain specific digits (numeric characters only, max 10 digits)
</ParamField>

### Response

<ResponseField name="data" type="array">
  Array of available phone numbers

  <Expandable title="available number properties">
    <ResponseField name="phone_number" type="string">
      The phone number in E.164 format
    </ResponseField>

    <ResponseField name="phone_number_formatted" type="string">
      The phone number formatted for display
    </ResponseField>

    <ResponseField name="country_code" type="string">
      The ISO country code
    </ResponseField>

    <ResponseField name="price" type="number">
      Monthly rental price in USD
    </ResponseField>

    <ResponseField name="stripe_price_id" type="string">
      The Stripe price ID for billing
    </ResponseField>

    <ResponseField name="address_requirements" type="string">
      Address requirements for this number: `none`, `local`, `foreign`, or `inventory`
    </ResponseField>

    <ResponseField name="sms_capable" type="boolean">
      Whether the number supports SMS
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": [
      {
        "phone_number": "+14155551234",
        "phone_number_formatted": "+1 415-555-1234",
        "country_code": "US",
        "price": 3.99,
        "stripe_price_id": "price_1PkA4dBXoZOzqQuAsvGvVJTZ",
        "address_requirements": "none",
        "sms_capable": true
      },
      {
        "phone_number": "+14155555678",
        "phone_number_formatted": "+1 415-555-5678",
        "country_code": "US",
        "price": 3.99,
        "stripe_price_id": "price_1PkA4dBXoZOzqQuAsvGvVJTZ",
        "address_requirements": "none",
        "sms_capable": false
      }
    ]
  }
  ```

  ```json 200 Empty Response theme={null}
  {
    "data": []
  }
  ```
</ResponseExample>

### Supported Countries

| Country        | Code |
| -------------- | ---- |
| United States  | US   |
| Canada         | CA   |
| United Kingdom | GB   |
| Australia      | AU   |
| Israel         | IL   |
| Poland         | PL   |
| Finland        | FI   |
| Netherlands    | NL   |
| Denmark        | DK   |
| Italy          | IT   |


# Update phone number
Source: https://docs.autocalls.ai/api-reference/phone-numbers/update-phone-number

PUT /user/phone-numbers/{id}
Update a phone number's nickname

This endpoint updates the editable attributes of a phone number you own. Currently this is the **nickname** — a short, human-friendly label (e.g. "Sales line", "Support — US") shown next to the number across the dashboard.

Only the **owner** of the number can update it. Numbers shared with you (granted) display the nickname but cannot be changed by you.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the phone number to update
</ParamField>

### Body Parameters

<ParamField type="string">
  A short label for the phone number. Maximum 50 characters. Send `null` or an empty string to clear it.
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  The updated phone number

  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the phone number
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The phone number in E.164 format
    </ResponseField>

    <ResponseField name="nickname" type="string">
      The phone number's nickname (or `null` if not set)
    </ResponseField>

    <ResponseField name="country_code" type="string">
      The ISO 3166-1 alpha-2 country code
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of phone number: `normal`, `sip`, or `caller_id`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "message": "Phone number updated successfully.",
    "data": {
      "id": 1,
      "phone_number": "+14155551234",
      "nickname": "Sales line",
      "country_code": "US",
      "type": "normal"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Phone number not found."
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The nickname must not exceed 50 characters.",
    "errors": {
      "nickname": ["The nickname must not exceed 50 characters."]
    }
  }
  ```
</ResponseExample>

<Note>
  The nickname is the same label you can set in the dashboard. It is returned by the phone number listing endpoints (`GET /user/phone-numbers/all`, `GET /user/phone-numbers/sip-trunks`), so other resources that reference a number by `phone_number_id` can resolve its nickname from there.
</Note>


# Create SIP trunk
Source: https://docs.autocalls.ai/api-reference/sip-trunks/create-sip-trunk

POST /user/phone-numbers/sip-trunks
Create a new SIP trunk with credentials, address, and proxy settings

This endpoint creates a new SIP trunk. The platform automatically provisions inbound and outbound trunks on the voice infrastructure using the provided credentials.

### Body Parameters

<ParamField type="string">
  The type of SIP trunk: `extension` for a SIP extension, or `number` for a phone number (DID). This determines the expected format of the `phone_number` field.
</ParamField>

<ParamField type="string">
  The SIP extension (1-15 characters, e.g. `1000`) when `sip_trunk_type` is `extension`, or a phone number in E.164 format (e.g. `+14155551234`) when `sip_trunk_type` is `number`.
</ParamField>

<ParamField type="string">
  A short, human-friendly label for the trunk (e.g. "Provider X — Main"). Maximum 50 characters.
</ParamField>

<ParamField type="string">
  Username for SIP authentication (3-128 characters)
</ParamField>

<ParamField type="string">
  Password for SIP authentication (minimum 3 characters)
</ParamField>

<ParamField type="string">
  The SIP server address without port (e.g. `sip.provider.com`)
</ParamField>

<ParamField type="string">
  The outbound calling number format:

  * `+e164` — International with `+` prefix (e.g. `+12025550123`)
  * `e164` — International without `+` prefix (e.g. `12025550123`)
  * `national` — National format without country code (e.g. `0741926265`)
</ParamField>

<ParamField type="string">
  How inbound calls are authenticated:

  * `auth` — Uses the same SIP username and password configured for outbound
  * `ip` — Whitelists specific IP addresses (requires `allowed_inbound_ips`)
</ParamField>

<ParamField type="array">
  Array of IP addresses allowed to send inbound calls. **Required** when `inbound_authorization_type` is `ip`. Must contain at least one valid IP address.
</ParamField>

<ParamField type="string">
  ISO 3166-2 country code where the SIP trunk is located (e.g. `US`, `GB`, `DE`). When `sip_trunk_type` is `number`, the country is auto-detected from the phone number if possible.
</ParamField>

<ParamField type="boolean">
  Route outbound calls through a fixed IP address. Default: `false`. Only enable this if your SIP provider requires IP-based authentication for outbound traffic.
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  The created SIP trunk object (same fields as [Get SIP trunk](/api-reference/sip-trunks/get-sip-trunk))
</ResponseField>

<ResponseExample>
  ```json 201 Extension with password auth theme={null}
  {
    "message": "SIP trunk created successfully.",
    "data": {
      "id": 42,
      "phone_number": "1000",
      "nickname": "Provider X — Main",
      "sip_username": "myuser",
      "sip_address": "sip.provider.com",
      "sip_calling_format": "+e164",
      "inbound_authorization_type": "auth",
      "allowed_inbound_ips": null,
      "outbound_proxy": false,
      "country_code": "US",
      "inbound_trunk_id": "ST_xxxxxxxxxxxx",
      "outbound_trunk_id": "ST_yyyyyyyyyyyy",
      "created_at": "2026-03-31T10:00:00.000000Z",
      "updated_at": "2026-03-31T10:00:00.000000Z"
    }
  }
  ```

  ```json 201 Phone number (DID) with IP auth theme={null}
  {
    "message": "SIP trunk created successfully.",
    "data": {
      "id": 43,
      "phone_number": "+14155551234",
      "nickname": null,
      "sip_username": "trunk_user",
      "sip_address": "sip.provider.com",
      "sip_calling_format": "e164",
      "inbound_authorization_type": "ip",
      "allowed_inbound_ips": ["203.0.113.10", "198.51.100.20"],
      "outbound_proxy": true,
      "country_code": "US",
      "inbound_trunk_id": "ST_xxxxxxxxxxxx",
      "outbound_trunk_id": "ST_yyyyyyyyyyyy",
      "created_at": "2026-03-31T10:00:00.000000Z",
      "updated_at": "2026-03-31T10:00:00.000000Z"
    }
  }
  ```

  ```json 409 Duplicate theme={null}
  {
    "error": "A SIP trunk with the same phone number, username, and address already exists."
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "sip_address": ["SIP server address is required."],
      "sip_calling_format": ["SIP calling format must be one of: +e164, e164, national."]
    }
  }
  ```

  ```json 500 Provisioning Error theme={null}
  {
    "error": "Failed to create SIP trunk. Please try again or contact support."
  }
  ```
</ResponseExample>

### What happens after creation

When you create a SIP trunk, the platform automatically:

1. **Provisions an inbound trunk** on the voice infrastructure — using either username/password or IP-based authentication depending on your `inbound_authorization_type` setting
2. **Provisions an outbound trunk** — using the SIP address and credentials you provided, optionally through the outbound proxy

If provisioning fails, the SIP trunk is not saved and a `500` error is returned.

### Next steps

After creating a SIP trunk, assign it to an AI assistant:

* **[Create Assistant](/api-reference/assistants/create-assistant)** — Use the `phone_number_id` parameter
* **[Update Assistant](/api-reference/assistants/update-assistant)** — Change the phone number on an existing assistant


# Delete SIP trunk
Source: https://docs.autocalls.ai/api-reference/sip-trunks/delete-sip-trunk

DELETE /user/phone-numbers/{id}
Delete a SIP trunk and clean up voice infrastructure

Deletes a SIP trunk and removes the associated inbound and outbound trunks from the voice infrastructure.

This uses the same endpoint as releasing any phone number. For SIP trunks, the deletion is immediate (no billing period).

<Note>
  See [Release phone number](/api-reference/phone-numbers/release-phone-number) for the full endpoint documentation. SIP trunks are immediately deleted and return `"Phone number deleted successfully."`.
</Note>

### Path Parameters

<ParamField type="integer">
  The unique identifier of the SIP trunk to delete
</ParamField>

### Response

<ResponseExample>
  ```json 200 Deleted theme={null}
  {
    "message": "Phone number deleted successfully."
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Phone number not found."
  }
  ```
</ResponseExample>

### What happens on deletion

When you delete a SIP trunk:

* **Inbound and outbound trunks** are removed from the voice infrastructure
* Any **assistants** using this SIP trunk will have their phone number unassigned
* Any **campaigns** using this number will have it removed from rotation
* **Call history** is preserved and remains accessible


# Get SIP trunk
Source: https://docs.autocalls.ai/api-reference/sip-trunks/get-sip-trunk

GET /user/phone-numbers/sip-trunks/{id}
Get a single SIP trunk by ID

This endpoint returns detailed information about a specific SIP trunk, including internal trunk IDs useful for debugging.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the SIP trunk
</ParamField>

### Response

<ResponseField name="data" type="object">
  The SIP trunk object

  <Expandable title="SIP trunk properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the SIP trunk
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The SIP extension or phone number (DID) in E.164 format
    </ResponseField>

    <ResponseField name="nickname" type="string">
      A short, human-friendly label for the trunk (or `null` if not set)
    </ResponseField>

    <ResponseField name="sip_username" type="string">
      The username used for SIP authentication
    </ResponseField>

    <ResponseField name="sip_address" type="string">
      The SIP server address
    </ResponseField>

    <ResponseField name="sip_calling_format" type="string">
      The outbound calling number format: `+e164`, `e164`, or `national`
    </ResponseField>

    <ResponseField name="inbound_authorization_type" type="string">
      The inbound authorization method: `auth` or `ip`
    </ResponseField>

    <ResponseField name="allowed_inbound_ips" type="array">
      Array of whitelisted IP addresses (only when `inbound_authorization_type` is `ip`)
    </ResponseField>

    <ResponseField name="outbound_proxy" type="boolean">
      Whether outbound calls use a fixed proxy IP address
    </ResponseField>

    <ResponseField name="country_code" type="string">
      The ISO 3166-2 country code
    </ResponseField>

    <ResponseField name="inbound_trunk_id" type="string">
      Internal identifier for the inbound voice trunk (useful for debugging)
    </ResponseField>

    <ResponseField name="outbound_trunk_id" type="string">
      Internal identifier for the outbound voice trunk (useful for debugging)
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": {
      "id": 42,
      "phone_number": "1000",
      "nickname": "Provider X — Main",
      "sip_username": "myuser",
      "sip_address": "sip.provider.com",
      "sip_calling_format": "+e164",
      "inbound_authorization_type": "auth",
      "allowed_inbound_ips": null,
      "outbound_proxy": false,
      "country_code": "US",
      "inbound_trunk_id": "ST_xxxxxxxxxxxx",
      "outbound_trunk_id": "ST_yyyyyyyyyyyy",
      "created_at": "2026-03-31T10:00:00.000000Z",
      "updated_at": "2026-03-31T10:00:00.000000Z"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "SIP trunk not found."
  }
  ```
</ResponseExample>


# List SIP trunks
Source: https://docs.autocalls.ai/api-reference/sip-trunks/list-sip-trunks

GET /user/phone-numbers/sip-trunks
Get all SIP trunks owned by the authenticated user

This endpoint returns a list of all SIP trunks associated with your account.

### Response

<ResponseField name="data" type="array">
  Array of SIP trunk objects

  <Expandable title="SIP trunk properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the SIP trunk
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The SIP extension or phone number (DID) in E.164 format
    </ResponseField>

    <ResponseField name="nickname" type="string">
      A short, human-friendly label for the trunk (or `null` if not set)
    </ResponseField>

    <ResponseField name="sip_username" type="string">
      The username used for SIP authentication
    </ResponseField>

    <ResponseField name="sip_address" type="string">
      The SIP server address
    </ResponseField>

    <ResponseField name="sip_calling_format" type="string">
      The outbound calling number format: `+e164`, `e164`, or `national`
    </ResponseField>

    <ResponseField name="inbound_authorization_type" type="string">
      The inbound authorization method: `auth` (username/password) or `ip` (IP whitelist)
    </ResponseField>

    <ResponseField name="allowed_inbound_ips" type="array">
      Array of whitelisted IP addresses for inbound calls (only when `inbound_authorization_type` is `ip`)
    </ResponseField>

    <ResponseField name="outbound_proxy" type="boolean">
      Whether outbound calls use a fixed proxy IP address
    </ResponseField>

    <ResponseField name="country_code" type="string">
      The ISO 3166-2 country code where the SIP trunk is located
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the SIP trunk was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of when the SIP trunk was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": [
      {
        "id": 42,
        "phone_number": "1000",
        "nickname": "Provider X — Main",
        "sip_username": "myuser",
        "sip_address": "sip.provider.com",
        "sip_calling_format": "+e164",
        "inbound_authorization_type": "auth",
        "allowed_inbound_ips": null,
        "outbound_proxy": false,
        "country_code": "US",
        "created_at": "2026-03-31T10:00:00.000000Z",
        "updated_at": "2026-03-31T10:00:00.000000Z"
      },
      {
        "id": 43,
        "phone_number": "+14155551234",
        "nickname": null,
        "sip_username": "trunk_user",
        "sip_address": "sip.provider.com",
        "sip_calling_format": "e164",
        "inbound_authorization_type": "ip",
        "allowed_inbound_ips": ["203.0.113.10", "198.51.100.20"],
        "outbound_proxy": true,
        "country_code": "US",
        "created_at": "2026-03-31T11:00:00.000000Z",
        "updated_at": "2026-03-31T11:00:00.000000Z"
      }
    ]
  }
  ```
</ResponseExample>


# Update SIP trunk
Source: https://docs.autocalls.ai/api-reference/sip-trunks/update-sip-trunk

PUT /user/phone-numbers/sip-trunks/{id}
Update an existing SIP trunk configuration

This endpoint updates an existing SIP trunk. Only include the fields you want to change — partial updates are supported. Changing credentials, address, or proxy settings automatically re-provisions the affected voice infrastructure trunks.

### Path Parameters

<ParamField type="integer">
  The unique identifier of the SIP trunk to update
</ParamField>

### Body Parameters

All fields are optional. Only send the fields you want to update.

<ParamField type="string">
  The SIP extension or phone number (1-15 characters)
</ParamField>

<ParamField type="string">
  A short, human-friendly label for the trunk. Maximum 50 characters. Send `null` to clear it.
</ParamField>

<ParamField type="string">
  Username for SIP authentication (3-128 characters)
</ParamField>

<ParamField type="string">
  Password for SIP authentication (minimum 3 characters)
</ParamField>

<ParamField type="string">
  The SIP server address without port
</ParamField>

<ParamField type="string">
  The outbound calling number format: `+e164`, `e164`, or `national`
</ParamField>

<ParamField type="string">
  How inbound calls are authenticated: `auth` or `ip`. When switching to `ip`, you must also provide `allowed_inbound_ips`. When switching to `auth`, any existing IP whitelist is cleared.
</ParamField>

<ParamField type="array">
  Array of IP addresses allowed for inbound calls. **Required** when `inbound_authorization_type` is set to `ip`.
</ParamField>

<ParamField type="string">
  ISO 3166-2 country code
</ParamField>

<ParamField type="boolean">
  Route outbound calls through a fixed IP address
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  The updated SIP trunk object (same fields as [Get SIP trunk](/api-reference/sip-trunks/get-sip-trunk))
</ResponseField>

<ResponseExample>
  ```json 200 Updated credentials theme={null}
  {
    "message": "SIP trunk updated successfully.",
    "data": {
      "id": 42,
      "phone_number": "1000",
      "nickname": "Provider X — Main",
      "sip_username": "new_username",
      "sip_address": "sip.provider.com",
      "sip_calling_format": "+e164",
      "inbound_authorization_type": "auth",
      "allowed_inbound_ips": null,
      "outbound_proxy": false,
      "country_code": "US",
      "inbound_trunk_id": "ST_newtrunkid1",
      "outbound_trunk_id": "ST_newtrunkid2",
      "created_at": "2026-03-31T10:00:00.000000Z",
      "updated_at": "2026-03-31T12:00:00.000000Z"
    }
  }
  ```

  ```json 200 Switched to IP auth theme={null}
  {
    "message": "SIP trunk updated successfully.",
    "data": {
      "id": 42,
      "phone_number": "1000",
      "nickname": "Provider X — Main",
      "sip_username": "myuser",
      "sip_address": "sip.provider.com",
      "sip_calling_format": "+e164",
      "inbound_authorization_type": "ip",
      "allowed_inbound_ips": ["203.0.113.10"],
      "outbound_proxy": false,
      "country_code": "US",
      "inbound_trunk_id": "ST_newtrunkid1",
      "outbound_trunk_id": "ST_yyyyyyyyyyyy",
      "created_at": "2026-03-31T10:00:00.000000Z",
      "updated_at": "2026-03-31T12:00:00.000000Z"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "SIP trunk not found."
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "allowed_inbound_ips": ["At least one allowed IP address is required when authorization type is \"ip\"."]
    }
  }
  ```

  ```json 500 Provisioning Error theme={null}
  {
    "error": "Failed to update SIP trunk. Please try again or contact support."
  }
  ```
</ResponseExample>

### Re-provisioning behavior

The following field changes trigger automatic re-provisioning of voice infrastructure trunks:

| Field changed                | Inbound trunk | Outbound trunk |
| ---------------------------- | :-----------: | :------------: |
| `sip_username`               |   Re-created  |   Re-created   |
| `sip_password`               |   Re-created  |   Re-created   |
| `sip_address`                |       —       |   Re-created   |
| `phone_number`               |   Re-created  |   Re-created   |
| `inbound_authorization_type` |   Re-created  |        —       |
| `allowed_inbound_ips`        |   Re-created  |        —       |
| `outbound_proxy`             |       —       |   Re-created   |

Fields like `sip_calling_format`, `country_code` are stored locally and do not trigger re-provisioning.


# Send SMS
Source: https://docs.autocalls.ai/api-reference/sms/send-sms

POST /user/sms
Send an SMS message using your phone number

This endpoint allows you to send SMS messages using your purchased phone numbers. The SMS will be sent via Twilio and costs will be automatically deducted from your account balance.

### Request Body

<ParamField type="integer">
  The ID of your phone number to send the SMS from (must be SMS-capable)
</ParamField>

<ParamField type="string">
  The recipient's phone number in international format (e.g., "+1234567890")
</ParamField>

<ParamField type="string">
  The SMS message content (max 300 characters)
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message confirming SMS was sent
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the SMS record
    </ResponseField>

    <ResponseField name="phone_number_id" type="integer">
      The ID of the phone number used to send the SMS
    </ResponseField>

    <ResponseField name="to" type="string">
      The recipient's phone number in E.164 format
    </ResponseField>

    <ResponseField name="body" type="string">
      The SMS message content
    </ResponseField>

    <ResponseField name="user_id" type="integer">
      The ID of the user who sent the SMS
    </ResponseField>

    <ResponseField name="segments" type="integer">
      Number of SMS segments (for billing purposes)
    </ResponseField>

    <ResponseField name="segment_price" type="number">
      Cost per SMS segment
    </ResponseField>

    <ResponseField name="total_cost" type="number">
      Total cost of the SMS (segment\_price \* segments)
    </ResponseField>

    <ResponseField name="status" type="string">
      The current status of the SMS
    </ResponseField>

    <ResponseField name="sms_sid" type="string">
      Twilio SMS SID for tracking
    </ResponseField>

    <ResponseField name="created_at" type="string">
      The date and time when the SMS was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      The date and time when the SMS was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

<ResponseField name="400 Bad Request">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message describing the issue (invalid phone number, insufficient balance, etc.)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="500 Internal Server Error">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Error message indicating SMS sending failure
    </ResponseField>

    <ResponseField name="error" type="string">
      Detailed error information
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Success Response theme={null}
  {
    "message": "SMS sent successfully",
    "data": {
      "id": 456,
      "phone_number_id": 78,
      "to": "+1234567890",
      "body": "Hello! This is a test message from Your Company. How can we help you today?",
      "user_id": 1,
      "segments": 1,
      "segment_price": 0.0075,
      "total_cost": 0.0075,
      "status": "sent",
      "sms_sid": "SM1234567890abcdef1234567890abcdef",
      "created_at": "2025-08-04 15:30:00",
      "updated_at": "2025-08-04 15:30:02"
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "message": "From number not found"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "message": "Invalid to phone number"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "message": "Insufficient balance"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "message": "From number is not SMS capable"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "message": "Failed to send SMS",
    "error": "Twilio API error details"
  }
  ```
</ResponseExample>

### Notes

* The sender phone number must belong to the authenticated user
* The sender phone number must be SMS-capable
* The phone number subscription must be active (not expired)
* Sufficient account balance is required to cover SMS costs
* Phone numbers are automatically formatted to E.164 format
* SMS costs vary by destination country and are charged per segment
* Long messages may be split into multiple segments, increasing the cost
* The recipient phone number must be valid according to international standards


# Get current user
Source: https://docs.autocalls.ai/api-reference/user/me

GET /user/me
Get the authenticated user's profile information

This endpoint returns the profile information for the currently authenticated user, including their account balance.

### Response

<ResponseField name="name" type="string">
  The user's full name
</ResponseField>

<ResponseField name="email" type="string">
  The user's email address
</ResponseField>

<ResponseField name="total_balance" type="number">
  The user's current account balance in USD
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "total_balance": 125.50
  }
  ```
</ResponseExample>

### Use Cases

This endpoint is useful for:

* **Verifying authentication** - Confirm the API key is valid and belongs to the expected user
* **Checking account balance** - Monitor available credits before making API calls
* **Displaying user info** - Show the current user in your application's UI


# Conversation Ended Webhook
Source: https://docs.autocalls.ai/api-reference/webhooks/conversation-ended-webhook

Webhook sent after a chat conversation ends containing transcript, extracted variables, and customer data

The Conversation Ended Webhook is automatically sent to your specified webhook URL after a chat conversation (WhatsApp or Web Widget) ends. This webhook contains the full transcript, extracted variables, customer information, and sender details.

## Webhook Configuration

To enable conversation ended webhooks:

1. Use the [Enable Conversation Ended Webhook](/api-reference/assistants/enable-conversation-ended-webhook) API endpoint
2. Provide your webhook URL where notifications will be sent
3. Optionally configure post-call variables on your assistant to extract structured data from conversations

## Request Format

The webhook is sent as a POST request to your configured URL with the following JSON payload:

### Payload Structure

<ResponseField name="id" type="integer">
  Numeric identifier of the conversation (the same id shown in the dashboard conversation URL). Use `conversation_id` (UUID) when calling the API.
</ResponseField>

<ResponseField name="conversation_id" type="string">
  Unique identifier (UUID) of the conversation
</ResponseField>

<ResponseField name="assistant_id" type="string">
  Unique identifier (UUID) of the assistant that handled the conversation
</ResponseField>

<ResponseField name="assistant_name" type="string">
  Name of the assistant that handled the conversation, as shown in the dashboard
</ResponseField>

<ResponseField name="type" type="string">
  The type of conversation. Possible values: `widget`, `whatsapp`, `api`, `messenger`, `instagram`
</ResponseField>

<ResponseField name="message_count" type="integer">
  Total number of messages exchanged in the conversation
</ResponseField>

<ResponseField name="status" type="string">
  Status of the conversation. Value: `ended`
</ResponseField>

<ResponseField name="extracted_variables" type="object">
  Variables extracted by AI based on your assistant's post-call schema configuration

  <Expandable title="Example extracted variables">
    <ResponseField name="status" type="boolean">
      Whether the conversation objective was achieved
    </ResponseField>

    <ResponseField name="summary" type="string">
      Conversation summary
    </ResponseField>

    <ResponseField name="custom_variable" type="string|number|boolean">
      Any custom variables you defined in the assistant configuration
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="input_variables" type="object">
  Variables that were passed to the assistant at the start of the conversation (e.g., from pre-chat form fields or automation flows)
</ResponseField>

<ResponseField name="transcript" type="array">
  Array of message objects representing the full conversation, ordered oldest to newest

  <Expandable title="Message properties">
    <ResponseField name="role" type="string">
      The sender role: `user`, `assistant`, or `system` (system messages mark events such as a human agent taking over the chat)
    </ResponseField>

    <ResponseField name="content" type="string">
      The message text. For media messages this is the caption or a short placeholder (e.g. `[Image]`); audio notes contain the transcribed text
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of the individual message, in the user's configured timezone. Lets you order messages and see how long a conversation spanned (useful for chats that run over several days)
    </ResponseField>

    <ResponseField name="timestamp_unix" type="integer">
      Unix timestamp (seconds since epoch) of the individual message. Convenient for arithmetic — e.g. computing the gap between two messages without parsing the ISO string
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="formatted_transcript" type="string">
  Human-readable formatted transcript with `AI:` and `Customer:` prefixes
</ResponseField>

<ResponseField name="attachments" type="array">
  Media files (images, videos, documents) shared during the conversation. Each entry includes a direct URL you can pass to external services (for example, image or video analysis). This is an empty array when no media was shared — media is typically present on WhatsApp conversations.

  <Expandable title="Attachment properties">
    <ResponseField name="type" type="string">
      The media category. Possible values: `image`, `video`, `audio`, `document`
    </ResponseField>

    <ResponseField name="url" type="string">
      Direct URL to download the media file
    </ResponseField>

    <ResponseField name="filename" type="string">
      Original file name of the media
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="customer_phone" type="string">
  Customer phone number (available for WhatsApp conversations, `null` for widget conversations)
</ResponseField>

<ResponseField name="customer_name" type="string">
  Customer name if provided (e.g., from pre-chat form), or `null`
</ResponseField>

<ResponseField name="sender" type="object">
  WhatsApp sender information (only present for WhatsApp conversations, `null` for widget)

  <Expandable title="Sender properties">
    <ResponseField name="phone_number" type="string">
      The WhatsApp sender phone number
    </ResponseField>

    <ResponseField name="display_name" type="string">
      The WhatsApp sender display name
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the conversation started (in the user's configured timezone)
</ResponseField>

<ResponseField name="ended_at" type="string">
  ISO 8601 timestamp when the conversation ended (in the user's configured timezone)
</ResponseField>

<ResponseExample>
  ```json Conversation Ended Webhook Payload theme={null}
  {
    "id": 8842,
    "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "assistant_name": "Support Chat",
    "type": "widget",
    "message_count": 8,
    "status": "ended",
    "extracted_variables": {
      "status": true,
      "summary": "Customer asked about pricing plans and was interested in the Pro plan"
    },
    "input_variables": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "transcript": [
      {
        "role": "assistant",
        "content": "Hi! How can I help you today?",
        "timestamp": "2026-02-23T09:30:00+01:00",
        "timestamp_unix": 1771835400
      },
      {
        "role": "user",
        "content": "I have a question about your service.",
        "timestamp": "2026-02-23T09:31:12+01:00",
        "timestamp_unix": 1771835472
      },
      {
        "role": "assistant",
        "content": "Of course! I'd be happy to help. What would you like to know?",
        "timestamp": "2026-02-23T09:31:15+01:00",
        "timestamp_unix": 1771835475
      },
      {
        "role": "user",
        "content": "What are your pricing plans?",
        "timestamp": "2026-02-23T09:58:40+01:00",
        "timestamp_unix": 1771837120
      }
    ],
    "formatted_transcript": "AI: Hi! How can I help you today?\nCustomer: I have a question about your service.\nAI: Of course! I'd be happy to help. What would you like to know?\nCustomer: What are your pricing plans?",
    "attachments": [],
    "customer_phone": null,
    "customer_name": "John Doe",
    "sender": null,
    "created_at": "2026-02-23T09:30:00+01:00",
    "ended_at": "2026-02-23T10:00:00+01:00"
  }
  ```

  ```json WhatsApp Conversation Ended Webhook theme={null}
  {
    "id": 8843,
    "conversation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "assistant_name": "Support Chat",
    "type": "whatsapp",
    "message_count": 12,
    "status": "ended",
    "extracted_variables": {
      "status": true,
      "summary": "Customer scheduled an appointment for next week"
    },
    "input_variables": {},
    "transcript": [
      {
        "role": "user",
        "content": "Hello, I'd like to book an appointment",
        "timestamp": "2026-02-23T14:00:05+01:00",
        "timestamp_unix": 1771851605
      },
      {
        "role": "assistant",
        "content": "Hi! I'd be happy to help you book an appointment. What date works best for you?",
        "timestamp": "2026-02-23T14:00:08+01:00",
        "timestamp_unix": 1771851608
      }
    ],
    "formatted_transcript": "Customer: Hello, I'd like to book an appointment\nAI: Hi! I'd be happy to help you book an appointment. What date works best for you?",
    "attachments": [
      {
        "type": "image",
        "url": "https://example.com/media/public/20032/product-photo.jpg",
        "filename": "product-photo.jpg"
      },
      {
        "type": "document",
        "url": "https://example.com/media/public/20031/order-receipt.pdf",
        "filename": "order-receipt.pdf"
      }
    ],
    "customer_phone": "+1234567890",
    "customer_name": null,
    "sender": {
      "phone_number": "+19876543210",
      "display_name": "My Business"
    },
    "created_at": "2026-02-23T14:00:00+01:00",
    "ended_at": "2026-02-23T14:25:00+01:00"
  }
  ```
</ResponseExample>

## Retry Behavior

If your webhook endpoint returns a non-2xx status code or the request fails, the system will retry:

| Attempt   | Delay       |
| --------- | ----------- |
| 1st retry | 30 seconds  |
| 2nd retry | 60 seconds  |
| 3rd retry | 120 seconds |

After 3 failed attempts, the webhook delivery is marked as failed and no further retries are attempted.

## Important Notes

* The `conversation_id` and `assistant_id` are UUIDs, not integer IDs
* `assistant_id`, `assistant_name`, and `type` let a single webhook URL serve several assistants — route on them instead of configuring a separate endpoint per assistant
* The `sender` field is only populated for WhatsApp conversations — it will be `null` for web widget conversations
* The `customer_phone` is only available for WhatsApp conversations
* The `customer_name` comes from pre-chat form data or conversation context
* Timestamps use the user's configured timezone (ISO 8601 format)
* The `extracted_variables` are populated from your assistant's post-call schema evaluation
* The `input_variables` contain data from pre-chat forms (web widget) or automation flows
* The `attachments` array lists media (images, videos, documents) shared during the conversation, each with a downloadable `url` — useful for forwarding to external analysis tools. It is an empty array when no media was shared (most common on web widget conversations)


# Post-Call Webhook
Source: https://docs.autocalls.ai/api-reference/webhooks/post-call-webhook

Webhook sent after a call is completed containing extracted variables and call data

The Post-Call Webhook is automatically sent to your specified webhook URL after each call is completed. This webhook contains call details, extracted variables, transcript, and optionally the recording URL.

## Webhook Configuration

To enable post-call webhooks:

1. Configure your assistant's webhook URL in the [assistant settings](/ai-assistants/settings/post-call-actions#webhook-configuration)
2. Enable "Post call webhook" in the [assistant configuration](/ai-assistants/settings/post-call-actions#webhook-configuration)
3. Define post-call variables that the AI should extract

## Request Format

The webhook is sent as a POST request to your configured URL with the following JSON payload:

<Tip>
  **Using one webhook URL for several assistants?** Every payload carries `assistant_id` (UUID), `assistant_name`, and `type`, so you can route each call without configuring a separate endpoint per assistant.
</Tip>

### Payload Structure

<ResponseField name="id" type="integer">
  Unique identifier of the call
</ResponseField>

<ResponseField name="type" type="string">
  Channel and direction of the call. One of `inbound`, `outbound`, `web` (browser widget voice call), `whatsapp_inbound`, or `whatsapp_outbound`
</ResponseField>

<ResponseField name="assistant_id" type="string">
  Unique identifier (UUID) of the assistant that handled the call
</ResponseField>

<ResponseField name="assistant_name" type="string">
  Name of the assistant that handled the call, as shown in the dashboard
</ResponseField>

<ResponseField name="customer_phone" type="string">
  Phone number of the customer in E.164 format (e.g., "+1234567890") or null if not available
</ResponseField>

<ResponseField name="assistant_phone" type="string">
  Phone number used by the assistant in E.164 format or null if not available
</ResponseField>

<ResponseField name="duration" type="integer">
  Duration of the call in seconds
</ResponseField>

<ResponseField name="status" type="string">
  Final status of the call (e.g., "completed", "busy", "failed")
</ResponseField>

<ResponseField name="extracted_variables" type="object">
  Variables extracted by AI based on your post-call schema configuration

  <Expandable title="Example extracted variables">
    <ResponseField name="status" type="boolean">
      Whether the call objective was achieved
    </ResponseField>

    <ResponseField name="summary" type="string">
      Call summary in a few words
    </ResponseField>

    <ResponseField name="custom_variable" type="string|number|boolean">
      Any custom variables you defined in the assistant configuration
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="input_variables" type="object">
  Variables that were passed to the assistant before the call started
</ResponseField>

<ResponseField name="transcript" type="array">
  Full transcript of the call, ordered oldest to newest. Note that this is a different shape from the [conversation ended webhook](/api-reference/webhooks/conversation-ended-webhook), which uses `role` and `content`

  <Expandable title="Transcript entry properties">
    <ResponseField name="type" type="string">
      What the entry represents: `transcript` for something that was said, `function` for a mid-call tool call or its result, `event` for a call event. Skip entries that are not `transcript` when rendering a conversation
    </ResponseField>

    <ResponseField name="text" type="string">
      What was said. Present on `transcript` entries
    </ResponseField>

    <ResponseField name="sender" type="string">
      Who said it: `bot` for the assistant, `human` for the customer
    </ResponseField>

    <ResponseField name="timestamp" type="number">
      Unix timestamp (seconds, with decimals) of the entry
    </ResponseField>

    <ResponseField name="metrics" type="object">
      Latency and model details for that turn (for example `tts_node_ttfb`, `e2e_latency`, `llm_metadata.model_name`). Keys vary per turn and provider, so treat every one as optional
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="formatted_transcript" type="string">
  The same conversation as a ready-to-read string, with `AI:` and `Customer:` prefixes and one turn per line. Use this when you just need readable text and do not want to iterate the array
</ResponseField>

<ResponseField name="recording_url" type="string">
  URL to download the call recording (only included if "Include recording in webhook" is enabled in [assistant settings](/ai-assistants/settings/post-call-actions#webhook-configuration))
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the call was initiated
</ResponseField>

<ResponseField name="finished_at" type="string">
  ISO 8601 timestamp when the call was completed (uses updated\_at from the call record)
</ResponseField>

<ResponseField name="lead" type="object">
  Lead information (only included for campaign calls)

  <Expandable title="Lead properties">
    <ResponseField name="id" type="integer">
      Unique identifier of the lead
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      Lead's phone number
    </ResponseField>

    <ResponseField name="variables" type="object">
      Variables associated with the lead
    </ResponseField>

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

    <ResponseField name="call_tries" type="integer">
      The number of call attempts made to this lead
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the lead was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the lead was last updated
    </ResponseField>

    <ResponseField name="campaign" type="object">
      Campaign information (if available)

      <Expandable title="Campaign properties">
        <ResponseField name="id" type="integer">
          Campaign ID
        </ResponseField>

        <ResponseField name="name" type="string">
          Campaign name
        </ResponseField>

        <ResponseField name="status" type="string">
          Campaign status
        </ResponseField>

        <ResponseField name="allowed_hours_start_time" type="string">
          Campaign allowed start time
        </ResponseField>

        <ResponseField name="allowed_hours_end_time" type="string">
          Campaign allowed end time
        </ResponseField>

        <ResponseField name="allowed_days" type="array">
          Campaign allowed days
        </ResponseField>

        <ResponseField name="max_calls_in_parallel" type="integer">
          Maximum concurrent calls for campaign
        </ResponseField>

        <ResponseField name="max_retries" type="integer">
          Maximum retry attempts for leads
        </ResponseField>

        <ResponseField name="retry_interval" type="integer">
          Retry interval in minutes
        </ResponseField>

        <ResponseField name="created_at" type="string">
          When the campaign was created
        </ResponseField>

        <ResponseField name="updated_at" type="string">
          When the campaign was last updated
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="transfers" type="array">
  List of transfer calls made during this call (only included if the call has transfers)

  <Expandable title="Transfer properties">
    <ResponseField name="id" type="integer">
      Unique identifier of the transfer call
    </ResponseField>

    <ResponseField name="status" type="string">
      Final status of the transfer call (e.g., "completed", "busy", "failed")
    </ResponseField>

    <ResponseField name="transfer_to" type="string">
      Phone number the call was transferred to in E.164 format
    </ResponseField>

    <ResponseField name="duration" type="integer">
      Duration of the transfer call in seconds
    </ResponseField>

    <ResponseField name="carrier_cost" type="number">
      Carrier cost of the transfer call in USD
    </ResponseField>

    <ResponseField name="transcript" type="array">
      Raw transcript of the transfer call (null if not available)
    </ResponseField>

    <ResponseField name="formatted_transcript" type="string">
      Human-readable formatted transcript of the transfer call
    </ResponseField>

    <ResponseField name="recording_url" type="string">
      URL to download the transfer call recording (only included if "Include recording in webhook" is enabled and a recording exists)
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp when the transfer was initiated
    </ResponseField>

    <ResponseField name="finished_at" type="string">
      ISO 8601 timestamp when the transfer was completed
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Post-Call Webhook Request theme={null}
  {
    "id": 12345,
    "type": "outbound",
    "assistant_id": "9c1f8e2a-4d3b-4a17-9f6e-2b5c8d0a7e31",
    "assistant_name": "Sales Agent",
    "customer_phone": "+1234567890",
    "assistant_phone": "+1987654321",
    "duration": 125,
    "status": "completed",
    "extracted_variables": {
      "status": true,
      "summary": "Customer interested in product demo",
      "lead_quality": "high",
      "next_action": "schedule_demo"
    },
    "input_variables": {
      "customer_name": "John Doe",
      "product_interest": "Pro Plan"
    },
    "transcript": [
      {
        "text": "Hello! This is Sarah from Autocalls. How are you today?",
        "type": "transcript",
        "sender": "bot",
        "timestamp": 1756812511.315143
      },
      {
        "text": "Hi, I'm doing well, thanks for calling.",
        "type": "transcript",
        "sender": "human",
        "timestamp": 1756812514.104436
      },
      {
        "text": "I'm calling to tell you about our new product features.",
        "type": "transcript",
        "sender": "bot",
        "timestamp": 1756812522.918859
      },
      {
        "text": "That sounds interesting, tell me more.",
        "type": "transcript",
        "sender": "human",
        "timestamp": 1756812525.234567
      }
    ],
    "formatted_transcript": "AI: Hello! This is Sarah from Autocalls. How are you today?\nCustomer: Hi, I'm doing well, thanks for calling.\nAI: I'm calling to tell you about our new product features.\nCustomer: That sounds interesting, tell me more.",
    "recording_url": "https://app.autocalls.ai/storage/recordings/call-12345.mp4",
    "created_at": "2025-01-15T10:30:00.000000Z",
    "finished_at": "2025-01-15T10:32:05.000000Z",
    "transfers": [
      {
        "id": 12346,
        "status": "completed",
        "transfer_to": "+1555123456",
        "duration": 85,
        "carrier_cost": 0.0156,
        "transcript": null,
        "formatted_transcript": "",
        "created_at": "2025-01-15T10:31:00.000000Z",
        "finished_at": "2025-01-15T10:32:25.000000Z"
      }
    ],
    "lead": {
      "id": 789,
      "phone_number": "+1234567890",
      "variables": {
        "source": "website",
        "interest_level": "high"
      },
      "status": "contacted",
      "call_tries": 2,
      "created_at": "2025-01-15T09:00:00.000000Z",
      "updated_at": "2025-01-15T10:32:05.000000Z",
      "campaign": {
        "id": 456,
        "name": "Product Demo Campaign",
        "status": "active",
        "allowed_hours_start_time": "09:00",
        "allowed_hours_end_time": "17:00",
        "allowed_days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
        "max_calls_in_parallel": 5,
        "max_retries": 3,
        "retry_interval": 60,
        "created_at": "2025-01-15T08:00:00.000000Z",
        "updated_at": "2025-01-15T08:00:00.000000Z"
      }
    }
  }
  ```
</ResponseExample>

## Webhook Settings

You can configure the following options for your post-call webhook:

* **Send webhook only on completed**: Only send the webhook for successfully completed calls
* **Include recording in webhook**: Include the `recording_url` field in the payload
* **Custom variables**: Define custom variables that the AI should extract from the conversation

## Important Notes

* The `type` field tells you both the channel and the direction of the call. Text conversations (web widget chat, WhatsApp messages) never arrive here — they use the [conversation ended webhook](/api-reference/webhooks/conversation-ended-webhook) instead. Completed WhatsApp **voice** calls do arrive here, as `whatsapp_inbound` or `whatsapp_outbound`
* The `assistant_id` is the assistant's UUID, the same identifier used by the other webhooks and by the API — not the numeric id shown in the dashboard URL
* The `customer_phone` and `assistant_phone` fields can be `null` if the information is not available
* The `recording_url` field is only included if you have enabled "Include recording in webhook" in your [assistant settings](/ai-assistants/settings/post-call-actions#webhook-configuration)
* The `lead` object is only included for calls that are part of a campaign
* The `transfers` array is only included for calls that have transfer calls associated with them
* The `extracted_variables` object will contain the variables you defined in your assistant's post-call schema configuration


# Read Receipts Webhook
Source: https://docs.autocalls.ai/api-reference/webhooks/read-receipts-webhook

Signed webhook sent on every delivery-status change (sent, delivered, read, failed) of a WhatsApp message you send

The Read Receipts Webhook delivers a signed HTTP callback to your server every time a WhatsApp message you send changes status — `sent`, `delivered`, `read`, or `failed`. Use it for delivery tracking, read confirmation, and audit trails.

It is configured **per WhatsApp sender**, so different senders can point at different endpoints.

## Webhook Configuration

To enable read receipts for a sender:

1. Edit your [WhatsApp sender](/whatsapp/senders) and open the **Read Receipts Webhook** section
2. Enter your **Webhook URL** and save
3. A **Signing Secret** is generated automatically — use it to verify the signature on each request

Each payload carries the `whatsapp_message_id` returned by the [Send Template](/api-reference/whatsapp/send-template) and [Send Free-form](/api-reference/whatsapp/send-freeform) endpoints, so you can match every update to the original message.

## Request Format

The webhook is sent as a POST request to your configured URL with a JSON body and an `X-Signature-256` header.

### Payload Structure

<ResponseField name="event" type="string">
  The event type. Value: `message_status`
</ResponseField>

<ResponseField name="whatsapp_message_id" type="integer">
  Numeric identifier of the message — the same `whatsapp_message_id` returned when you sent the message. Use this to correlate the status update with the original send.
</ResponseField>

<ResponseField name="message_sid" type="string">
  Provider message identifier for messages sent over Twilio, or `null`
</ResponseField>

<ResponseField name="meta_message_id" type="string">
  Provider message identifier (WhatsApp `wamid`) for messages sent over the Meta Cloud API, or `null`
</ResponseField>

<ResponseField name="conversation_id" type="string">
  Unique identifier (UUID) of the conversation the message belongs to, or `null`
</ResponseField>

<ResponseField name="assistant_id" type="string">
  Unique identifier (UUID) of the assistant connected to the sender, or `null`
</ResponseField>

<ResponseField name="sender" type="object">
  The WhatsApp sender the message was sent from

  <Expandable title="Sender properties">
    <ResponseField name="id" type="integer">
      Numeric identifier of the sender
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The sender's WhatsApp phone number
    </ResponseField>

    <ResponseField name="display_name" type="string">
      The sender's display name
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="to" type="string">
  The recipient phone number
</ResponseField>

<ResponseField name="from" type="string">
  The sender phone number
</ResponseField>

<ResponseField name="direction" type="string">
  Message direction. Value: `outbound`
</ResponseField>

<ResponseField name="status" type="string">
  The new delivery status. Possible values: `sent`, `delivered`, `read`, `failed`, `undelivered`
</ResponseField>

<ResponseField name="error_code" type="integer">
  Provider error code when `status` is `failed` or `undelivered`, otherwise `null`
</ResponseField>

<ResponseField name="error_message" type="string">
  Raw provider error message when the message failed, otherwise `null`
</ResponseField>

<ResponseField name="error_description" type="string">
  Human-readable description of the error, otherwise `null`
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 timestamp of when the platform recorded the status change, in the WhatsApp number owner's configured timezone
</ResponseField>

<ResponseField name="provider_timestamp" type="string">
  ISO 8601 timestamp of the carrier's own event time, in the owner's configured timezone. Present for messages sent over the Meta Cloud API; `null` over Twilio (Twilio's status callback does not include an event time). Prefer this when present — it is the carrier's authoritative time.
</ResponseField>

<ResponseExample>
  ```json Delivered theme={null}
  {
    "event": "message_status",
    "whatsapp_message_id": 890,
    "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "meta_message_id": null,
    "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "sender": {
      "id": 42,
      "phone_number": "+19876543210",
      "display_name": "My Business"
    },
    "to": "+1234567890",
    "from": "+19876543210",
    "direction": "outbound",
    "status": "delivered",
    "error_code": null,
    "error_message": null,
    "error_description": null,
    "timestamp": "2026-06-08T09:30:02+00:00",
    "provider_timestamp": "2026-06-08T09:30:00+00:00"
  }
  ```

  ```json Read theme={null}
  {
    "event": "message_status",
    "whatsapp_message_id": 890,
    "message_sid": null,
    "meta_message_id": "wamid.HBgLMTIzNDU2Nzg5MBUCABEYEjk...",
    "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "sender": {
      "id": 42,
      "phone_number": "+19876543210",
      "display_name": "My Business"
    },
    "to": "+1234567890",
    "from": "+19876543210",
    "direction": "outbound",
    "status": "read",
    "error_code": null,
    "error_message": null,
    "error_description": null,
    "timestamp": "2026-06-08T09:31:12+00:00",
    "provider_timestamp": "2026-06-08T09:31:10+00:00"
  }
  ```

  ```json Failed theme={null}
  {
    "event": "message_status",
    "whatsapp_message_id": 891,
    "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "meta_message_id": null,
    "conversation_id": null,
    "assistant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "sender": {
      "id": 42,
      "phone_number": "+19876543210",
      "display_name": "My Business"
    },
    "to": "+1234567890",
    "from": "+19876543210",
    "direction": "outbound",
    "status": "failed",
    "error_code": 63016,
    "error_message": "Template message 24h window expired",
    "error_description": "Template message 24h window expired - customer must reply first",
    "timestamp": "2026-06-08T09:32:00+00:00",
    "provider_timestamp": null
  }
  ```
</ResponseExample>

## Verifying the Signature

Every request includes an `X-Signature-256` header containing an HMAC-SHA256 of the **raw request body**, keyed with your sender's **Signing Secret**:

```
X-Signature-256: sha256=<hmac_sha256(raw_body, signing_secret)>
```

Recompute the signature over the raw body and compare it using a constant-time comparison. Reject the request if it does not match.

<CodeGroup>
  ```javascript Node.js theme={null}
  import crypto from "crypto";

  function isValid(rawBody, signatureHeader, secret) {
    const expected =
      "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
    return crypto.timingSafeEqual(
      Buffer.from(expected),
      Buffer.from(signatureHeader || "")
    );
  }
  ```

  ```php PHP theme={null}
  function isValid(string $rawBody, ?string $signatureHeader, string $secret): bool
  {
      $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);

      return hash_equals($expected, (string) $signatureHeader);
  }
  ```
</CodeGroup>

## Retry Behavior

If your endpoint returns a non-2xx status or the request fails, delivery is retried:

| Attempt   | Delay       |
| --------- | ----------- |
| 1st retry | 30 seconds  |
| 2nd retry | 60 seconds  |
| 3rd retry | 120 seconds |

Server errors (5xx) and rate limits (429) are retried. Client errors (4xx) are treated as a misconfigured endpoint and are not retried.

## Important Notes

* The webhook is configured **per sender** — each sender can have its own URL and secret.
* Events triggered by the **Make test request** button in the sender settings include an extra `test: true` field and use placeholder values. Real status updates never include `test`.
* `read` only fires if the recipient has read receipts enabled in their WhatsApp privacy settings. `delivered` always fires.
* Statuses can arrive out of order or be re-sent by the provider. We only forward genuine forward progress, so you won't receive a `delivered` after a `read` for the same message — but you should still treat the webhook as the source of truth and de-duplicate by `whatsapp_message_id` + `status`.
* `timestamp` is always the time the platform recorded the change (in the number owner's timezone). `provider_timestamp` is the carrier's authoritative event time when available — prefer it for accuracy, and fall back to `timestamp` when it is `null`.
* Use **Regenerate** in the sender settings to rotate the signing secret if it is ever exposed.


# WhatsApp Voice Webhook
Source: https://docs.autocalls.ai/api-reference/webhooks/whatsapp-voice-webhook

Events when a customer is asked to allow WhatsApp calls, answers that request, or a WhatsApp call starts

We POST compact WhatsApp calling events when a contact is asked to allow calls, answers that request, or a WhatsApp call starts.

This is how you listen for "they allowed the call" without polling.

<Info>
  **Automations** — use the **WhatsApp voice event** trigger. That binds a dedicated webhook and will not overwrite your New conversation flow.

  **Custom backends** — events are also POSTed to the assistant's conversation webhook URL (the same URL used for new-conversation notifications). Filter incoming POSTs on `"event": "whatsapp_voice"`.
</Info>

Completed WhatsApp calls still use the [post-call webhook](/api-reference/webhooks/post-call-webhook). Inbound WhatsApp calls that your assistant answers also follow the assistant's inbound webhook, if you have one.

## Event types

| `type`                      | When it fires                                               |
| --------------------------- | ----------------------------------------------------------- |
| `call_permission_requested` | You sent Ask to call                                        |
| `call_permission_granted`   | Customer tapped Allow                                       |
| `call_permission_denied`    | Customer tapped Decline                                     |
| `voice_call`                | A WhatsApp call was placed or received (includes `call_id`) |

## Payload

Every voice event is a small JSON object. It does **not** include provider IDs, trunks, recordings, transcripts, or costs.

<ResponseField name="event" type="string">
  Always `whatsapp_voice`
</ResponseField>

<ResponseField name="type" type="string">
  One of the event types above
</ResponseField>

<ResponseField name="sender_id" type="integer">
  WhatsApp sender that owns the chat
</ResponseField>

<ResponseField name="customer_phone" type="string">
  Customer number in E.164
</ResponseField>

<ResponseField name="conversation_id" type="string">
  Conversation UUID, or `null`
</ResponseField>

<ResponseField name="assistant_id" type="string">
  Assistant UUID
</ResponseField>

<ResponseField name="assistant_name" type="string">
  Assistant name, as shown in the dashboard
</ResponseField>

<ResponseField name="status" type="string">
  Current permission status: `pending`, `granted`, `rejected`, `revoked`, `expired`, or `null`
</ResponseField>

<ResponseField name="expires_at" type="string">
  When granted consent ends, or `null`
</ResponseField>

<ResponseField name="can_call" type="boolean">
  Whether you may place a WhatsApp call right now
</ResponseField>

<ResponseField name="call_id" type="integer">
  Present only on `voice_call`. Dashboard call id.
</ResponseField>

<ResponseField name="direction" type="string">
  Present only on `voice_call`: `whatsapp_outbound` or `whatsapp_inbound`
</ResponseField>

<ResponseExample>
  ```json Permission granted theme={null}
  {
    "event": "whatsapp_voice",
    "type": "call_permission_granted",
    "sender_id": 12,
    "customer_phone": "+40711222333",
    "conversation_id": "9c2e1d4a-6b8f-4c11-9a0e-1f2d3c4b5a67",
    "assistant_id": "b7e2c1aa-11d0-4f3a-9c44-0d8e7f6a5b21",
    "assistant_name": "Support Chat",
    "status": "granted",
    "expires_at": "2026-08-22T10:15:00+00:00",
    "can_call": true
  }
  ```

  ```json Outbound call started theme={null}
  {
    "event": "whatsapp_voice",
    "type": "voice_call",
    "sender_id": 12,
    "customer_phone": "+40711222333",
    "conversation_id": "9c2e1d4a-6b8f-4c11-9a0e-1f2d3c4b5a67",
    "assistant_id": "b7e2c1aa-11d0-4f3a-9c44-0d8e7f6a5b21",
    "assistant_name": "Support Chat",
    "status": "granted",
    "expires_at": "2026-08-22T10:15:00+00:00",
    "can_call": true,
    "call_id": 18402,
    "direction": "whatsapp_outbound"
  }
  ```
</ResponseExample>

## Typical automation

1. Customer replies to your template (24-hour window opens)
2. You [request permission](/api-reference/whatsapp/request-call-permission)
3. Your server receives `call_permission_granted`
4. You [place the call](/api-reference/whatsapp/place-whatsapp-call)
5. You receive `voice_call`, then later the [post-call webhook](/api-reference/webhooks/post-call-webhook)

If you never receive `call_permission_granted`, the customer declined, ignored the card, or the ask never delivered. Check [Get call permission](/api-reference/whatsapp/get-call-permission) and [WhatsApp Calling](/whatsapp/calling).

## Delivery

* POST JSON, 10 second timeout, up to 3 retries
* Respond with HTTP 2xx so we do not retry
* Ignore events whose `event` is not `whatsapp_voice` if you also use this URL for new conversations


# Get call permission
Source: https://docs.autocalls.ai/api-reference/whatsapp/get-call-permission

GET /user/whatsapp/voice/permission
Check whether a contact can be asked to call, or already allowed WhatsApp calls

Returns the current WhatsApp calling permission for one sender and one customer phone number. Use this before you [ask](/api-reference/whatsapp/request-call-permission) or [place a call](/api-reference/whatsapp/place-whatsapp-call).

<Note>
  Rate-limited to **20 requests per minute** per user.
</Note>

### Query Parameters

<ParamField type="integer">
  WhatsApp sender ID from [Get Senders](/api-reference/whatsapp/get-senders)
</ParamField>

<ParamField type="string">
  Customer phone number in E.164 format (e.g. `+40711222333`)
</ParamField>

### Response Fields

<ResponseField name="success" type="boolean">
  Request succeeded
</ResponseField>

<ResponseField name="sender_id" type="integer">
  The sender you queried
</ResponseField>

<ResponseField name="customer_phone" type="string">
  Normalized E.164 phone number
</ResponseField>

<ResponseField name="conversation_id" type="string">
  Conversation UUID if a chat already exists, otherwise `null`
</ResponseField>

<ResponseField name="status" type="string">
  `pending`, `granted`, `rejected`, `revoked`, `expired`, or `null` if never asked
</ResponseField>

<ResponseField name="can_call" type="boolean">
  `true` only when consent is granted and still valid
</ResponseField>

<ResponseField name="can_request" type="boolean">
  `true` when the 24-hour chat window is open and WhatsApp still allows another ask
</ResponseField>

<ResponseField name="session_open" type="boolean">
  `true` when the customer messaged this sender in the last 24 hours
</ResponseField>

<ResponseField name="expires_at" type="string">
  When granted consent ends (ISO 8601), or `null`
</ResponseField>

<ResponseField name="requested_at" type="string">
  When the last ask was sent (ISO 8601), or `null`
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.autocalls.ai/api/user/whatsapp/voice/permission?sender_id=12&recipient_phone=%2B40711222333" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    sender_id: '12',
    recipient_phone: '+40711222333',
  });

  const response = await fetch(
    `https://app.autocalls.ai/api/user/whatsapp/voice/permission?${params}`,
    { headers: { Authorization: 'Bearer YOUR_API_KEY' } }
  );

  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://app.autocalls.ai/api/user/whatsapp/voice/permission',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={'sender_id': 12, 'recipient_phone': '+40711222333'},
  )

  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Ready to ask theme={null}
  {
    "success": true,
    "sender_id": 12,
    "customer_phone": "+40711222333",
    "conversation_id": "9c2e1d4a-6b8f-4c11-9a0e-1f2d3c4b5a67",
    "status": null,
    "can_call": false,
    "can_request": true,
    "session_open": true,
    "expires_at": null,
    "requested_at": null
  }
  ```

  ```json 200 Consent granted theme={null}
  {
    "success": true,
    "sender_id": 12,
    "customer_phone": "+40711222333",
    "conversation_id": "9c2e1d4a-6b8f-4c11-9a0e-1f2d3c4b5a67",
    "status": "granted",
    "can_call": true,
    "can_request": false,
    "session_open": true,
    "expires_at": "2026-08-22T10:15:00+00:00",
    "requested_at": "2026-08-15T10:15:00+00:00"
  }
  ```

  ```json 404 Sender not found theme={null}
  {
    "success": false,
    "error": "Sender not found or does not belong to you",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```
</ResponseExample>

### Notes

* Only senders that belong to your account are visible. A missing or foreign `sender_id` returns `SENDER_NOT_FOUND`.
* `can_request` is `false` when the chat window is closed — send a [regular template](/api-reference/whatsapp/send-template) and wait for a reply first. See [WhatsApp Calling](/whatsapp/calling).
* `can_request` and `can_call` are also `false` when the sender's country does not allow business-initiated WhatsApp calls (United States, Canada, Egypt, Vietnam, Nigeria, Türkiye). Inbound calls still work.


# Get WhatsApp Senders
Source: https://docs.autocalls.ai/api-reference/whatsapp/get-senders

GET /user/whatsapp/senders
List all WhatsApp Business senders for the authenticated user

This endpoint returns a list of WhatsApp Business senders (phone numbers) configured for your account. Use this to retrieve sender IDs needed for sending messages.

### Query Parameters

<ParamField type="string">
  Filter senders by status. Default: `online`. Use `all` to return all senders regardless of status.
</ParamField>

### Response Fields

<ResponseField name="data" type="array">
  <Expandable title="Sender object properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the WhatsApp sender. Use this ID when sending messages.
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The sender's phone number in E.164 format (e.g., `+14155551234`)
    </ResponseField>

    <ResponseField name="display_name" type="string">
      The WhatsApp Business display name (business name shown to recipients)
    </ResponseField>

    <ResponseField name="status" type="string">
      The sender's current status: `online` or `offline`
    </ResponseField>

    <ResponseField name="quality_rating" type="string">
      Meta's quality rating for this sender: `GREEN`, `YELLOW`, or `RED`
    </ResponseField>

    <ResponseField name="messaging_limit" type="integer">
      The current messaging limit (number of unique recipients per 24 hours). `null` means unlimited.
    </ResponseField>

    <ResponseField name="messaging_limit_formatted" type="string">
      Human-readable messaging limit (e.g., `1,000 / 24hr`, `10,000 / 24hr`, or `Unlimited`)
    </ResponseField>

    <ResponseField name="voice_calling_enabled" type="boolean">
      `true` when WhatsApp Calling is enabled on this sender. See [WhatsApp Calling](/whatsapp/calling).
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.autocalls.ai/api/user/whatsapp/senders" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash Filter all senders theme={null}
  curl -X GET "https://app.autocalls.ai/api/user/whatsapp/senders?status=all" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.autocalls.ai/api/user/whatsapp/senders',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(data.data); // Array of senders
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://app.autocalls.ai/api/user/whatsapp/senders',
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

  senders = response.json()['data']
  for sender in senders:
      print(f"{sender['display_name']}: {sender['phone_number']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": [
      {
        "id": 12,
        "phone_number": "+14155551234",
        "display_name": "Acme Corp Support",
        "status": "online",
        "quality_rating": "GREEN",
        "messaging_limit": 10000,
        "messaging_limit_formatted": "10,000 / 24hr",
        "voice_calling_enabled": true
      },
      {
        "id": 15,
        "phone_number": "+442071234567",
        "display_name": "Acme Corp Sales",
        "status": "online",
        "quality_rating": "GREEN",
        "messaging_limit": null,
        "messaging_limit_formatted": "Unlimited",
        "voice_calling_enabled": false
      }
    ]
  }
  ```

  ```json 200 Empty Response theme={null}
  {
    "data": []
  }
  ```
</ResponseExample>

### Notes

* Only senders with status `online` are returned by default. Use `?status=all` to include offline senders.
* Sender status is synced with Meta every 5 minutes automatically.
* The `id` field is what you need to pass as `sender_id` when sending messages.
* Quality rating affects your messaging limits. A `RED` rating may restrict your ability to send messages.


# Get Templates
Source: https://docs.autocalls.ai/api-reference/whatsapp/get-templates

GET /user/whatsapp/senders/{senderId}/templates
List WhatsApp message templates for a specific sender

This endpoint returns all message templates associated with a specific WhatsApp sender. Templates are required for initiating conversations or messaging users outside the 24-hour messaging window.

### Path Parameters

<ParamField type="integer">
  The ID of the WhatsApp sender (obtained from the [Get Senders](/api-reference/whatsapp/get-senders) endpoint)
</ParamField>

### Query Parameters

<ParamField type="string">
  Filter templates by approval status. Default: `approved`. Use `all` to return all templates regardless of status.
</ParamField>

### Response Fields

<ResponseField name="data" type="array">
  <Expandable title="Template object properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the template. Use this when sending template messages.
    </ResponseField>

    <ResponseField name="name" type="string">
      The template name as registered with Meta (e.g., `order_confirmation`, `appointment_reminder`)
    </ResponseField>

    <ResponseField name="language" type="string">
      The template language code (e.g., `en`, `es`, `pt_BR`)
    </ResponseField>

    <ResponseField name="category" type="string">
      The template category: `marketing`, `utility`, or `authentication`
    </ResponseField>

    <ResponseField name="status" type="string">
      The approval status: `approved`, `pending`, or `rejected`
    </ResponseField>

    <ResponseField name="body_text" type="string">
      The template body text, with variable placeholders shown as `{{1}}`, `{{2}}`, etc.
    </ResponseField>

    <ResponseField name="variables" type="array">
      List of variable names defined for the template. Empty array if the template has no variables.
    </ResponseField>

    <ResponseField name="has_variables" type="boolean">
      Whether this template requires variables to be provided when sending
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">
      `false`
    </ResponseField>

    <ResponseField name="error" type="string">
      `Sender not found`
    </ResponseField>

    <ResponseField name="error_code" type="string">
      `SENDER_NOT_FOUND`
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.autocalls.ai/api/user/whatsapp/senders/12/templates" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash All templates (including pending/rejected) theme={null}
  curl -X GET "https://app.autocalls.ai/api/user/whatsapp/senders/12/templates?status=all" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const senderId = 12;

  const response = await fetch(
    `https://app.autocalls.ai/api/user/whatsapp/senders/${senderId}/templates`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(data.data); // Array of templates
  ```

  ```python Python theme={null}
  import requests

  sender_id = 12

  response = requests.get(
      f'https://app.autocalls.ai/api/user/whatsapp/senders/{sender_id}/templates',
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

  templates = response.json()['data']
  for template in templates:
      print(f"{template['name']} ({template['language']}): {template['body_text']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": [
      {
        "id": 45,
        "name": "appointment_reminder",
        "language": "en",
        "category": "utility",
        "status": "approved",
        "body_text": "Hi {{1}}, this is a reminder for your appointment on {{2}} at {{3}}. Reply YES to confirm or NO to reschedule.",
        "variables": ["customer_name", "date", "time"],
        "has_variables": true
      },
      {
        "id": 46,
        "name": "welcome_message",
        "language": "en",
        "category": "marketing",
        "status": "approved",
        "body_text": "Welcome to Acme Corp! We're excited to have you. How can we help you today?",
        "variables": [],
        "has_variables": false
      }
    ]
  }
  ```

  ```json 404 Sender Not Found theme={null}
  {
    "success": false,
    "error": "Sender not found",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```
</ResponseExample>

### Notes

* Only `approved` templates are returned by default. Templates with `pending` or `rejected` status cannot be used to send messages.
* Template approval status is synced with Meta every 4 hours automatically.
* Variables in `body_text` are shown as `{{1}}`, `{{2}}`, etc. The `variables` array provides human-readable names for each placeholder.
* Templates are required when messaging a user for the first time or outside the 24-hour messaging window.


# Place a WhatsApp call
Source: https://docs.autocalls.ai/api-reference/whatsapp/place-whatsapp-call

POST /user/whatsapp/voice/call
Place an outbound WhatsApp voice call after the customer has granted permission

Queues an outbound WhatsApp voice call. Your sender's assistant joins the call when the customer answers.

The customer **must** have granted call permission and that consent must still be valid. This endpoint will not call a number that never allowed calling.

<Note>
  Rate-limited to **5 requests per minute**, **15 per hour**, and **30 per day** per user. Also limited to **3 attempts per contact every 5 minutes** and **5 WhatsApp calls in progress** on the same sender.
</Note>

### Request Body

<ParamField type="integer">
  WhatsApp sender ID with calling enabled
</ParamField>

<ParamField type="string">
  Customer phone number in E.164 format
</ParamField>

<ParamField type="object">
  Optional variables passed to the assistant (max 20 keys, string values up to 500 characters). Use the same names you configured on the assistant.
</ParamField>

### Response Fields

<ResponseField name="success" type="boolean">
  The call was queued
</ResponseField>

<ResponseField name="status" type="string">
  Always `queued` on success. The call is placed asynchronously.
</ResponseField>

<ResponseField name="sender_id" type="integer">
  Sender used for the call
</ResponseField>

<ResponseField name="customer_phone" type="string">
  Normalized E.164 phone number
</ResponseField>

### Error codes

| HTTP | `error_code`           | Meaning                                                                     |
| ---- | ---------------------- | --------------------------------------------------------------------------- |
| 402  | `INSUFFICIENT_BALANCE` | Account balance is too low                                                  |
| 403  | `ASSISTANT_BLOCKED`    | Assistant is unavailable for compliance review                              |
| 404  | `SENDER_NOT_FOUND`     | Sender missing or not yours                                                 |
| 422  | `INVALID_PHONE`        | Phone is not valid E.164                                                    |
| 422  | `VOICE_DISABLED`       | Calling is not enabled                                                      |
| 422  | `NO_PERMISSION`        | Customer has not granted (or consent expired)                               |
| 422  | `NO_ASSISTANT`         | Sender has no assistant                                                     |
| 422  | `SENDER_OFFLINE`       | Sender is not online                                                        |
| 422  | `REGION_NOT_SUPPORTED` | WhatsApp does not allow business-initiated calls from this sender's country |
| 422  | `FEATURE_DISABLED`     | Calling is not available on this workspace                                  |
| 429  | `CONCURRENT_LIMIT`     | Too many WhatsApp calls already ringing on this sender                      |
| 429  | `CONTACT_RATE_LIMIT`   | Too many attempts to this contact in the last 5 minutes                     |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.autocalls.ai/api/user/whatsapp/voice/call" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "recipient_phone": "+40711222333",
      "variables": {
        "customer_name": "Ana Pop"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.autocalls.ai/api/user/whatsapp/voice/call',
    {
      method: 'POST',
      headers: {
        Authorization: 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        sender_id: 12,
        recipient_phone: '+40711222333',
        variables: { customer_name: 'Ana Pop' },
      }),
    }
  );

  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://app.autocalls.ai/api/user/whatsapp/voice/call',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'sender_id': 12,
          'recipient_phone': '+40711222333',
          'variables': {'customer_name': 'Ana Pop'},
      },
  )

  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Queued theme={null}
  {
    "success": true,
    "status": "queued",
    "sender_id": 12,
    "customer_phone": "+40711222333"
  }
  ```

  ```json 422 No permission theme={null}
  {
    "success": false,
    "error": "This contact has not granted permission to receive WhatsApp calls. Send a call permission request first.",
    "error_code": "NO_PERMISSION"
  }
  ```
</ResponseExample>

### After you queue the call

* A `call_started` event is sent to the [WhatsApp voice webhook](/api-reference/webhooks/whatsapp-voice-webhook) when the call is placed
* When the call finishes, the assistant's [post-call webhook](/api-reference/webhooks/post-call-webhook) fires as usual (transcript, duration, extracted variables)
* The response does **not** include provider call IDs

Read [WhatsApp Calling](/whatsapp/calling) before you automate this. Cold-calling new numbers is not possible.


# Request call permission
Source: https://docs.autocalls.ai/api-reference/whatsapp/request-call-permission

POST /user/whatsapp/voice/request
Send a WhatsApp Voice Call Request (Ask to call) to a customer

Sends the sender's approved Voice Call Request template so the customer can Allow or Decline WhatsApp calls.

This endpoint will **not** send the request if the 24-hour chat window is closed. That protects your WhatsApp quota: a request sent to a brand-new number is not delivered, but still counts as your one ask for the day.

<Note>
  Rate-limited to **5 requests per minute**, **20 per hour**, and **50 per day** per user. WhatsApp typically allows **1 ask per contact every 24 hours** and **2 per week**. Those WhatsApp counters reset after a connected call.
</Note>

### Request Body

<ParamField type="integer">
  WhatsApp sender ID. Calling must already be enabled on this sender.
</ParamField>

<ParamField type="string">
  Customer phone number in E.164 format
</ParamField>

<ParamField type="string">
  Optional display name for the conversation (max 255 characters)
</ParamField>

<ParamField type="integer">
  Optional Voice Call Request template ID. If omitted, the sender's approved voice-call template is used.
</ParamField>

### Response Fields

Same shape as [Get call permission](/api-reference/whatsapp/get-call-permission), plus `success`.

### Error codes

| HTTP | `error_code`           | Meaning                                                                                                                   |
| ---- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| 404  | `SENDER_NOT_FOUND`     | Sender missing or not yours                                                                                               |
| 422  | `INVALID_PHONE`        | Phone is not valid E.164                                                                                                  |
| 422  | `VOICE_DISABLED`       | Calling is not enabled on this sender                                                                                     |
| 422  | `TEMPLATE_NOT_FOUND`   | No approved Voice Call Request template                                                                                   |
| 422  | `SESSION_CLOSED`       | Customer has not messaged you in the last 24 hours                                                                        |
| 422  | `REQUEST_LIMIT`        | Already asked in the last 24 hours (and no connected call reset the counter), weekly cap reached, or they already granted |
| 422  | `REGION_NOT_SUPPORTED` | WhatsApp does not allow business-initiated calls from this sender's country (US, CA, EG, VN, NG, TR)                      |
| 422  | `SEND_FAILED`          | WhatsApp rejected the send                                                                                                |
| 429  | —                      | API rate limit                                                                                                            |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.autocalls.ai/api/user/whatsapp/voice/request" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "recipient_phone": "+40711222333",
      "recipient_name": "Ana Pop"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.autocalls.ai/api/user/whatsapp/voice/request',
    {
      method: 'POST',
      headers: {
        Authorization: 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        sender_id: 12,
        recipient_phone: '+40711222333',
        recipient_name: 'Ana Pop',
      }),
    }
  );

  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://app.autocalls.ai/api/user/whatsapp/voice/request',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'sender_id': 12,
          'recipient_phone': '+40711222333',
          'recipient_name': 'Ana Pop',
      },
  )

  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "sender_id": 12,
    "customer_phone": "+40711222333",
    "conversation_id": "9c2e1d4a-6b8f-4c11-9a0e-1f2d3c4b5a67",
    "status": "pending",
    "can_call": false,
    "can_request": false,
    "session_open": true,
    "expires_at": null,
    "requested_at": "2026-08-15T10:15:00+00:00"
  }
  ```

  ```json 422 Session closed theme={null}
  {
    "success": false,
    "error": "This contact has not messaged you in the last 24 hours. Send a regular template first and wait for their reply, then ask to call.",
    "error_code": "SESSION_CLOSED"
  }
  ```
</ResponseExample>

### Recommended flow

1. [Send a regular template](/api-reference/whatsapp/send-template) if there is no open chat
2. Wait for the customer to reply (or poll [session status](/api-reference/whatsapp/session-status))
3. Call this endpoint
4. Listen for `call_permission_granted` on the [voice webhook](/api-reference/webhooks/whatsapp-voice-webhook)
5. [Place the call](/api-reference/whatsapp/place-whatsapp-call)

See [WhatsApp Calling](/whatsapp/calling) for the product rules behind these errors.


# Send Freeform Message
Source: https://docs.autocalls.ai/api-reference/whatsapp/send-freeform

POST /user/whatsapp/send-freeform
Send a free-text WhatsApp message within an active 24-hour session

This endpoint sends a freeform (free-text) WhatsApp message to a recipient. Unlike template messages, freeform messages can contain any text but **require an active 24-hour messaging window** — meaning the recipient must have sent a message to your WhatsApp sender within the last 24 hours.

<Warning>
  Freeform messages can only be sent during an active 24-hour messaging window. If the session has expired, you must send a [template message](/api-reference/whatsapp/send-template) first to re-initiate the conversation. Use the [Session Status](/api-reference/whatsapp/session-status) endpoint to check if a session is active.
</Warning>

<Note>
  This endpoint is rate-limited to **5 requests per second** per user.
</Note>

### Request Body

<ParamField type="integer">
  The ID of the WhatsApp sender to send from (obtained from the [Get Senders](/api-reference/whatsapp/get-senders) endpoint)
</ParamField>

<ParamField type="string">
  The recipient's phone number in international format (e.g., `+1234567890`)
</ParamField>

<ParamField type="string">
  The message content to send (max 4096 characters). Optional when `media_url` is provided — in that case it is used as the media caption. **Audio files are the exception: WhatsApp does not support captions on audio, so the text is ignored when `media_url` points to an audio file.** **Either `message` or `media_url` is required.**
</ParamField>

<ParamField type="string">
  Optional public URL of a file to send — an image, audio file, video, or document. The file must be reachable at a public URL (WhatsApp fetches it at send time). When set, `message` is used as the caption for images, videos and documents. **Audio files cannot carry a caption — if you send an audio file, any `message` text is ignored.** **Either `message` or `media_url` is required.**
</ParamField>

<ParamField type="string">
  Optional filename shown to the recipient, mainly useful for documents (e.g. `invoice.pdf`).
</ParamField>

### Response Fields

<ResponseField name="success" type="boolean">
  Whether the message was sent successfully
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  The ID of the conversation associated with this message
</ResponseField>

<ResponseField name="message_id" type="integer">
  The ID of the conversation message record
</ResponseField>

<ResponseField name="whatsapp_message_id" type="integer">
  The ID of the WhatsApp message record
</ResponseField>

<ResponseField name="message_sid" type="string">
  The Twilio message SID for tracking delivery
</ResponseField>

<ResponseField name="session_status" type="object">
  Updated session status after sending the message

  <Expandable title="Session status properties">
    <ResponseField name="is_open" type="boolean">
      Whether the 24-hour messaging window is currently open
    </ResponseField>

    <ResponseField name="can_send_freeform" type="boolean">
      Whether freeform messages can be sent right now
    </ResponseField>

    <ResponseField name="requires_template" type="boolean">
      Whether a template message is required
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable description of the session state
    </ResponseField>

    <ResponseField name="minutes_remaining" type="integer">
      Minutes remaining in the 24-hour window
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      ISO 8601 timestamp when the session expires
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

<ResponseField name="402 Insufficient Balance">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Insufficient balance. Please top up your account.`</ResponseField>
    <ResponseField name="error_code" type="string">`INSUFFICIENT_BALANCE`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="403 Session Expired">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Message indicating the 24-hour messaging window has expired</ResponseField>
    <ResponseField name="error_code" type="string">`SESSION_EXPIRED`</ResponseField>

    <ResponseField name="session_status" type="object">
      Current session status with `is_open`, `can_send_freeform`, `requires_template`, and `message` fields
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Sender not found or does not belong to you`</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_NOT_FOUND`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="503 Sender Offline">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Message indicating the sender is currently offline</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_OFFLINE`</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.autocalls.ai/api/user/whatsapp/send-freeform" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "recipient_phone": "+1234567890",
      "message": "Thank you for your inquiry! Our team will review your request and get back to you within 2 hours."
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.autocalls.ai/api/user/whatsapp/send-freeform',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        sender_id: 12,
        recipient_phone: '+1234567890',
        message: 'Thank you for your inquiry! Our team will review your request and get back to you within 2 hours.'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://app.autocalls.ai/api/user/whatsapp/send-freeform',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'sender_id': 12,
          'recipient_phone': '+1234567890',
          'message': 'Thank you for your inquiry! Our team will review your request and get back to you within 2 hours.'
      }
  )

  print(response.json())
  ```

  ```bash cURL (with media) theme={null}
  curl -X POST "https://app.autocalls.ai/api/user/whatsapp/send-freeform" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "recipient_phone": "+1234567890",
      "message": "Here is the menu you asked for!",
      "media_url": "https://example.com/files/menu.pdf",
      "filename": "menu.pdf"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "conversation_id": 1234,
    "message_id": 567,
    "whatsapp_message_id": 890,
    "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "session_status": {
      "is_open": true,
      "can_send_freeform": true,
      "requires_template": false,
      "message": "Session open (23 hr 45 min remaining). Unlimited free-form messages allowed.",
      "minutes_remaining": 1425,
      "expires_at": "2026-02-25T10:30:00+00:00"
    }
  }
  ```

  ```json 402 Insufficient Balance theme={null}
  {
    "success": false,
    "error": "Insufficient balance. Please top up your account.",
    "error_code": "INSUFFICIENT_BALANCE"
  }
  ```

  ```json 403 Session Expired theme={null}
  {
    "success": false,
    "error": "The 24-hour messaging window is closed. Customer must reply first, or use a template message.",
    "error_code": "SESSION_EXPIRED",
    "session_status": {
      "is_open": false,
      "can_send_freeform": false,
      "requires_template": true,
      "message": "Session expired. Send a template or wait for customer to reply.",
      "expired_at": "2026-02-23T10:30:00+00:00"
    }
  }
  ```

  ```json 404 Sender Not Found theme={null}
  {
    "success": false,
    "error": "Sender not found or does not belong to you",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```

  ```json 422 Invalid Phone theme={null}
  {
    "success": false,
    "error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).",
    "error_code": "INVALID_PHONE"
  }
  ```

  ```json 503 Sender Offline theme={null}
  {
    "success": false,
    "error": "Sender is not online. Current status: Offline",
    "error_code": "SENDER_OFFLINE"
  }
  ```
</ResponseExample>

### 24-Hour Messaging Window

WhatsApp enforces a **24-hour messaging window** policy:

1. When a customer sends a message to your WhatsApp Business number, a 24-hour window opens.
2. During this window, you can send freeform messages without restrictions.
3. After the window expires, you must use a [template message](/api-reference/whatsapp/send-template) to re-initiate the conversation.
4. Each new customer message resets the 24-hour timer.

Use the [Session Status](/api-reference/whatsapp/session-status) endpoint to check whether a session is active before attempting to send a freeform message.

### Notes

* Maximum message length is **4,096 characters** (WhatsApp limit).
* A file (image, audio, video, or document) can be attached with `media_url`. It must be hosted at a publicly reachable URL — WhatsApp fetches it at send time. When sending media, `message` is optional and is used as the caption. **Audio is the exception: WhatsApp does not support captions on audio files, so when `media_url` points to an audio file the `message` text is not sent.**
* The sender must be `online`. Offline senders return a `503` error.
* Message costs are automatically deducted from your account balance.
* Rate limit: 5 requests per second per user.


# Send Template Message
Source: https://docs.autocalls.ai/api-reference/whatsapp/send-template

POST /user/whatsapp/send
Send a WhatsApp message using an approved template

This endpoint sends a WhatsApp message using a pre-approved template. Template messages are required when initiating a conversation with a user for the first time or when messaging outside the 24-hour messaging window.

<Note>
  This endpoint is rate-limited to **5 requests per second** per user.
</Note>

### Request Body

<ParamField type="integer">
  The ID of the WhatsApp sender to send from (obtained from the [Get Senders](/api-reference/whatsapp/get-senders) endpoint)
</ParamField>

<ParamField type="integer">
  The ID of the message template to use (obtained from the [Get Templates](/api-reference/whatsapp/get-templates) endpoint)
</ParamField>

<ParamField type="string">
  The recipient's phone number in international format (e.g., `+1234567890`)
</ParamField>

<ParamField type="string">
  The recipient's name, max 255 characters (used for conversation tracking and CRM purposes)
</ParamField>

<ParamField type="object">
  Key-value pairs for template variables. Keys should match the variable names from the template. If the template has variables `{{1}}`, `{{2}}`, etc., provide them as `{"1": "value1", "2": "value2"}` or using the named keys from the template's `variables` array.

  <Expandable title="Example variables">
    <ParamField type="string">
      Value for the first template variable
    </ParamField>

    <ParamField type="string">
      Value for the second template variable
    </ParamField>
  </Expandable>
</ParamField>

### Response Fields

<ResponseField name="success" type="boolean">
  Whether the message was sent successfully
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  The ID of the conversation (new or existing) associated with this message
</ResponseField>

<ResponseField name="message_id" type="integer">
  The ID of the conversation message record
</ResponseField>

<ResponseField name="whatsapp_message_id" type="integer">
  The ID of the WhatsApp message record
</ResponseField>

<ResponseField name="message_sid" type="string">
  The Twilio message SID for tracking delivery
</ResponseField>

<ResponseField name="status" type="string">
  The initial message delivery status (e.g., `queued`, `sent`)
</ResponseField>

### Error Responses

<ResponseField name="402 Insufficient Balance">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Insufficient balance. Please top up your account.`</ResponseField>
    <ResponseField name="error_code" type="string">`INSUFFICIENT_BALANCE`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Sender not found or does not belong to you` or `Template not found or does not belong to this sender`</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_NOT_FOUND` or `TEMPLATE_NOT_FOUND`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="422 Unprocessable Entity">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Detailed error message</ResponseField>

    <ResponseField name="error_code" type="string">
      One of: `SENDER_OFFLINE`, `TEMPLATE_NOT_APPROVED`, `TEMPLATE_NOT_SYNCED`, `TEMPLATE_MISMATCH`, `NO_ASSISTANT_CONFIGURED`, `INVALID_PHONE`, `MESSAGING_LIMIT_UNAVAILABLE`, `VOICE_CALL_LIMIT_NOT_MET`, `TWILIO_ERROR_{code}`, `UNKNOWN_ERROR`
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.autocalls.ai/api/user/whatsapp/send" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "template_id": 45,
      "recipient_phone": "+1234567890",
      "recipient_name": "John Doe",
      "variables": {
        "1": "John",
        "2": "January 15, 2026",
        "3": "2:00 PM"
      }
    }'
  ```

  ```bash Template without variables theme={null}
  curl -X POST "https://app.autocalls.ai/api/user/whatsapp/send" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "template_id": 46,
      "recipient_phone": "+1234567890"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.autocalls.ai/api/user/whatsapp/send',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        sender_id: 12,
        template_id: 45,
        recipient_phone: '+1234567890',
        recipient_name: 'John Doe',
        variables: {
          '1': 'John',
          '2': 'January 15, 2026',
          '3': '2:00 PM'
        }
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://app.autocalls.ai/api/user/whatsapp/send',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'sender_id': 12,
          'template_id': 45,
          'recipient_phone': '+1234567890',
          'recipient_name': 'John Doe',
          'variables': {
              '1': 'John',
              '2': 'January 15, 2026',
              '3': '2:00 PM'
          }
      }
  )

  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "conversation_id": 1234,
    "message_id": 567,
    "whatsapp_message_id": 890,
    "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "queued"
  }
  ```

  ```json 402 Insufficient Balance theme={null}
  {
    "success": false,
    "error": "Insufficient balance. Please top up your account.",
    "error_code": "INSUFFICIENT_BALANCE"
  }
  ```

  ```json 404 Sender Not Found theme={null}
  {
    "success": false,
    "error": "Sender not found or does not belong to you",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```

  ```json 404 Template Not Found theme={null}
  {
    "success": false,
    "error": "Template not found or does not belong to this sender",
    "error_code": "TEMPLATE_NOT_FOUND"
  }
  ```

  ```json 422 Template Not Approved theme={null}
  {
    "success": false,
    "error": "Template is not approved. Current status: pending",
    "error_code": "TEMPLATE_NOT_APPROVED"
  }
  ```

  ```json 422 Invalid Phone theme={null}
  {
    "success": false,
    "error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).",
    "error_code": "INVALID_PHONE"
  }
  ```

  ```json 422 Sender Offline theme={null}
  {
    "success": false,
    "error": "Sender is not online. Current status: Offline",
    "error_code": "SENDER_OFFLINE"
  }
  ```
</ResponseExample>

### Notes

* Template messages must use **approved** templates. Templates with `pending` or `rejected` status will fail.
* The sender must be `online`. Offline senders cannot send messages.
* Message costs are automatically deducted from your account balance (credits for tenant users, minutes for direct users).
* After sending a template message, a 24-hour messaging window opens. During this window, you can send [freeform messages](/api-reference/whatsapp/send-freeform) without needing a template.
* If a conversation already exists with the recipient, the message is added to the existing conversation.
* Rate limit: 5 requests per second per user.


# Get Session Status
Source: https://docs.autocalls.ai/api-reference/whatsapp/session-status

GET /user/whatsapp/session-status
Check the 24-hour messaging window status for a WhatsApp conversation

This endpoint checks whether an active 24-hour messaging window exists between your WhatsApp sender and a specific recipient. Use this to determine whether you can send [freeform messages](/api-reference/whatsapp/send-freeform) or need to use a [template message](/api-reference/whatsapp/send-template).

### Query Parameters

<ParamField type="integer">
  The ID of the WhatsApp sender (obtained from the [Get Senders](/api-reference/whatsapp/get-senders) endpoint)
</ParamField>

<ParamField type="string">
  The recipient's phone number in international format (e.g., `+1234567890`)
</ParamField>

### Response Fields

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

<ResponseField name="has_conversation" type="boolean">
  Whether a conversation exists with this recipient
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  The conversation ID (only present when `has_conversation` is `true`)
</ResponseField>

<ResponseField name="customer_name" type="string">
  The customer's name if available (only present when `has_conversation` is `true`)
</ResponseField>

<ResponseField name="last_customer_message_at" type="string">
  ISO 8601 timestamp of the customer's last message (only present when `has_conversation` is `true`)
</ResponseField>

<ResponseField name="session_status" type="object">
  <Expandable title="Session status properties">
    <ResponseField name="is_open" type="boolean">
      Whether the 24-hour messaging window is currently open
    </ResponseField>

    <ResponseField name="can_send_freeform" type="boolean">
      Whether freeform (non-template) messages can be sent right now
    </ResponseField>

    <ResponseField name="requires_template" type="boolean">
      Whether a template message is required to message this recipient
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable description of the current session state
    </ResponseField>

    <ResponseField name="minutes_remaining" type="integer">
      Minutes remaining in the 24-hour window (only present when session is open)
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      ISO 8601 timestamp when the session expires (present when session is open or no customer message exists)
    </ResponseField>

    <ResponseField name="expired_at" type="string">
      ISO 8601 timestamp when the session expired (only present when session has expired)
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Sender not found`</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_NOT_FOUND`</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.autocalls.ai/api/user/whatsapp/session-status?sender_id=12&recipient_phone=+1234567890" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    sender_id: '12',
    recipient_phone: '+1234567890'
  });

  const response = await fetch(
    `https://app.autocalls.ai/api/user/whatsapp/session-status?${params}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  if (data.session_status.can_send_freeform) {
    console.log('Session is active — freeform messages allowed');
  } else {
    console.log('Session expired — use a template message');
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://app.autocalls.ai/api/user/whatsapp/session-status',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={
          'sender_id': 12,
          'recipient_phone': '+1234567890'
      }
  )

  data = response.json()
  session = data['session_status']

  if session['can_send_freeform']:
      print('Session is active — freeform messages allowed')
  else:
      print('Session expired — use a template message')
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Active Session theme={null}
  {
    "success": true,
    "has_conversation": true,
    "conversation_id": 1234,
    "customer_name": "John Doe",
    "last_customer_message_at": "2026-02-24T10:30:00+00:00",
    "session_status": {
      "is_open": true,
      "can_send_freeform": true,
      "requires_template": false,
      "message": "Session open (23 hr 45 min remaining). Unlimited free-form messages allowed.",
      "minutes_remaining": 1425,
      "expires_at": "2026-02-25T10:30:00+00:00"
    }
  }
  ```

  ```json 200 Expired Session theme={null}
  {
    "success": true,
    "has_conversation": true,
    "conversation_id": 1234,
    "customer_name": "John Doe",
    "last_customer_message_at": "2026-02-22T14:00:00+00:00",
    "session_status": {
      "is_open": false,
      "can_send_freeform": false,
      "requires_template": true,
      "message": "Session expired. Send a template or wait for customer to reply.",
      "expired_at": "2026-02-23T14:00:00+00:00"
    }
  }
  ```

  ```json 200 No Conversation theme={null}
  {
    "success": true,
    "has_conversation": false,
    "session_status": {
      "is_open": false,
      "can_send_freeform": false,
      "requires_template": true,
      "message": "No conversation exists with this recipient. Send a template message first."
    }
  }
  ```

  ```json 404 Sender Not Found theme={null}
  {
    "success": false,
    "error": "Sender not found",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```
</ResponseExample>

### Typical Workflow

Use this endpoint as part of a message-sending flow:

1. **Check session status** before sending a message
2. If `can_send_freeform` is `true` → use [Send Freeform Message](/api-reference/whatsapp/send-freeform)
3. If `requires_template` is `true` → use [Send Template Message](/api-reference/whatsapp/send-template)

### Notes

* The 24-hour window is based on the customer's last inbound message timestamp.
* Each new customer message resets the 24-hour timer.
* This endpoint does not consume any balance — it's a read-only status check.


# Create user token
Source: https://docs.autocalls.ai/api-reference/white-label/create-token

POST /white-label/token
Generate an API token for a platform user without requiring their password

This endpoint allows white label admins to generate an API token for any of their platform users without needing the user's password. Use this to programmatically access user data for building dashboards, email sequences, or automated workflows.

<Note>
  This endpoint requires authentication as a **white label admin**. Only users belonging to your platform can have tokens generated.
</Note>

### Request Body

<ParamField type="integer">
  The platform user's ID. Required if `email` is not provided.
</ParamField>

<ParamField type="string">
  The platform user's email address. Required if `user_id` is not provided.
</ParamField>

<ParamField type="string">
  Optional name/label for the API token (e.g., "kpi-dashboard", "email-automation"). Defaults to "api-token".
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="user" type="object">
  The user's information

  <Expandable title="user properties">
    <ResponseField name="id" type="integer">
      The user's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string">
      The user's full name
    </ResponseField>

    <ResponseField name="email" type="string">
      The user's email address
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="token" type="string">
  The API token for the platform user
</ResponseField>

<ResponseField name="token_name" type="string">
  The name/label of the token
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "message": "Token created successfully.",
    "user": {
      "id": 123,
      "name": "John Doe",
      "email": "john@example.com"
    },
    "token": "2|abc123xyz789...",
    "token_name": "api-token"
  }
  ```

  ```json 404 User Not Found theme={null}
  {
    "error": "User not found."
  }
  ```

  ```json 403 Not White Label Admin theme={null}
  {
    "error": "You are not an administrator."
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The user id field is required when email is not present. (and 1 more error)",
    "errors": {
      "user_id": ["The user id field is required when email is not present."],
      "email": ["The email field is required when user id is not present."]
    }
  }
  ```
</ResponseExample>

### Example Request

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/white-label/token \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 123
  }'
```

Or by email:

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/white-label/token \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "platformuser@example.com",
    "token_name": "kpi-dashboard"
  }'
```

### Using the User Token

The returned token belongs to the platform user and can be used for their authenticated requests:

```bash theme={null}
curl -X GET https://app.autocalls.ai/api/user/calls?date_from=2026-03-01&per_page=100 \
  -H "Authorization: Bearer 2|abc123xyz789..."
```

### Building a KPI Dashboard

To build a dashboard with all your users' data:

1. **List your users** — `GET /api/white-label/users` with your admin key
2. **Generate a token for each user** — `POST /api/white-label/token` with their `user_id`
3. **Fetch each user's data** using their token:
   * `GET /api/user/calls` — call history with duration, status, cost
   * `GET /api/user/campaigns` — campaign statuses
   * `GET /api/user/leads` — leads with statuses
   * `GET /api/user/me` — profile and balance info

<Tip>
  Tokens never expire, so you only need to generate them once per user. Store the tokens and reuse them for subsequent API calls.
</Tip>


# Get platform users
Source: https://docs.autocalls.ai/api-reference/white-label/get-users

GET /white-label/users
Get all users belonging to your white label platform

This endpoint returns a list of all users that belong to your white label platform. Use this to display user lists and manage your platform users.

<Note>
  This endpoint is only available for **white label admins**. Regular users will receive a 403 Forbidden error.
</Note>

### Response

<ResponseField name="data" type="array">
  Array of user objects

  <Expandable title="user properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the user
    </ResponseField>

    <ResponseField name="name" type="string">
      The user's full name
    </ResponseField>

    <ResponseField name="email" type="string">
      The user's email address
    </ResponseField>

    <ResponseField name="minutes_balance" type="number">
      The user's current call minutes balance
    </ResponseField>

    <ResponseField name="credits_balance" type="number">
      The user's current chat credits balance
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the user was created
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "data": [
      {
        "id": 123,
        "name": "John Doe",
        "email": "john@example.com",
        "minutes_balance": 150.5,
        "credits_balance": 500,
        "created_at": "2025-01-05T10:30:00.000000Z"
      },
      {
        "id": 124,
        "name": "Jane Smith",
        "email": "jane@example.com",
        "minutes_balance": 75.25,
        "credits_balance": 250,
        "created_at": "2025-01-06T14:20:00.000000Z"
      }
    ]
  }
  ```

  ```json 200 Empty Response theme={null}
  {
    "data": []
  }
  ```

  ```json 403 Not White Label Admin theme={null}
  {
    "error": "You are not a white label admin."
  }
  ```
</ResponseExample>

### Use Cases

* **Display user list** in your custom white label management dashboard
* **Lookup user IDs** for use with the [transfer balance](/api-reference/white-label/transfer-balance) endpoint
* **Monitor user balances** to identify users who need credits


# Login platform user
Source: https://docs.autocalls.ai/api-reference/white-label/login

POST /white-label/login
Authenticate a platform user and receive an API token

This endpoint allows white label admins to authenticate one of their platform users and receive an API token for that user. Use this to build custom authentication flows for your white label platform.

<Note>
  This endpoint requires authentication as a **white label admin**. Only users belonging to your platform can be logged in.
</Note>

### Request Body

<ParamField type="string">
  The platform user's email address
</ParamField>

<ParamField type="string">
  The platform user's password
</ParamField>

<ParamField type="string">
  Optional name/label for the API token (e.g., "Mobile App", "Web Dashboard"). Defaults to "api-token".
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="user" type="object">
  The authenticated user's information

  <Expandable title="user properties">
    <ResponseField name="id" type="integer">
      The user's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string">
      The user's full name
    </ResponseField>

    <ResponseField name="email" type="string">
      The user's email address
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="token" type="string">
  The API token for the platform user
</ResponseField>

<ResponseField name="token_name" type="string">
  The name/label of the token
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "message": "Login successful.",
    "user": {
      "id": 123,
      "name": "John Doe",
      "email": "john@example.com"
    },
    "token": "2|abc123xyz789...",
    "token_name": "api-token"
  }
  ```

  ```json 401 Invalid Credentials theme={null}
  {
    "message": "These credentials do not match our records.",
    "errors": {
      "email": ["These credentials do not match our records."]
    }
  }
  ```

  ```json 403 Not White Label Admin theme={null}
  {
    "error": "You are not a white label admin."
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The email field is required.",
    "errors": {
      "email": ["The email field is required."]
    }
  }
  ```
</ResponseExample>

### Example Request

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/white-label/login \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "platformuser@example.com",
    "password": "userpassword123",
    "token_name": "Mobile App"
  }'
```

### Using the User Token

The returned token belongs to the platform user and can be used for their authenticated requests:

```bash theme={null}
curl -X GET https://app.autocalls.ai/api/user/me \
  -H "Authorization: Bearer 2|abc123xyz789..."
```


# Logout platform user
Source: https://docs.autocalls.ai/api-reference/white-label/logout

POST /white-label/logout
Revoke API tokens for a platform user

This endpoint allows white label admins to revoke API tokens for one of their platform users, effectively logging them out.

<Note>
  This endpoint requires authentication as a **white label admin**. You can only logout users belonging to your platform.
</Note>

### Request Body

<ParamField type="integer">
  The ID of the user to logout. Required if `email` is not provided.
</ParamField>

<ParamField type="string">
  The email of the user to logout. Required if `user_id` is not provided.
</ParamField>

<ParamField type="integer">
  Optional. The specific token ID to revoke. If not provided, all tokens for the user will be revoked.
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "message": "User logged out successfully."
  }
  ```

  ```json 403 Not White Label Admin theme={null}
  {
    "error": "You are not a white label admin."
  }
  ```

  ```json 404 User Not Found theme={null}
  {
    "error": "User not found."
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "Either user_id or email is required.",
    "errors": {
      "user_id": ["Either user_id or email is required."]
    }
  }
  ```
</ResponseExample>

### Example: Logout by Email (All Tokens)

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/white-label/logout \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "platformuser@example.com"
  }'
```

### Example: Logout Specific Token

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/white-label/logout \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 123,
    "token_id": 45
  }'
```


# Register platform user
Source: https://docs.autocalls.ai/api-reference/white-label/register

POST /white-label/register
Register a new platform user account

This endpoint allows white label admins to create a new user account on their platform. The new user will automatically be associated with your white label platform.

<Note>
  This endpoint requires authentication as a **white label admin**. The created user will belong to your platform.
</Note>

### Request Body

<ParamField type="string">
  The user's full name
</ParamField>

<ParamField type="string">
  The user's email address (must be unique within your platform)
</ParamField>

<ParamField type="string">
  The user's password (minimum 8 characters)
</ParamField>

<ParamField type="string">
  The user's timezone (e.g., "America/New\_York"). Defaults to "Europe/Bucharest".
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="user" type="object">
  The newly created user's information

  <Expandable title="user properties">
    <ResponseField name="id" type="integer">
      The user's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string">
      The user's full name
    </ResponseField>

    <ResponseField name="email" type="string">
      The user's email address
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="token" type="string">
  The API token for the new platform user
</ResponseField>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "message": "Registration successful.",
    "user": {
      "id": 123,
      "name": "John Doe",
      "email": "john@example.com"
    },
    "token": "2|abc123xyz789..."
  }
  ```

  ```json 403 Not White Label Admin theme={null}
  {
    "error": "You are not a white label admin."
  }
  ```

  ```json 422 Email Already Exists theme={null}
  {
    "message": "The email has already been taken.",
    "errors": {
      "email": ["The email has already been taken."]
    }
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The password field must be at least 8 characters.",
    "errors": {
      "password": ["The password field must be at least 8 characters."]
    }
  }
  ```
</ResponseExample>

### Example Request

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/white-label/register \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "securepassword123",
    "timezone": "America/New_York"
  }'
```


# Transfer balance
Source: https://docs.autocalls.ai/api-reference/white-label/transfer-balance

POST /white-label/transfer
Transfer minutes or credits to/from a platform user

This endpoint allows white label admins to transfer call minutes or chat credits to and from their users. This is useful for managing user balances programmatically when building custom frontends.

<Note>
  This endpoint is only available for **white label admins**. Regular users will receive a 403 Forbidden error.
</Note>

### Request Body

<ParamField type="integer">
  The ID of the user to transfer to/from. Required if `email` is not provided.
</ParamField>

<ParamField type="string">
  The email of the user to transfer to/from. Required if `user_id` is not provided.
</ParamField>

<ParamField type="string">
  The type of balance to transfer: `minutes` or `credits`
</ParamField>

<ParamField type="string">
  The operation to perform: `add` (transfer to user) or `remove` (transfer from user)
</ParamField>

<ParamField type="number">
  The amount to transfer. For minutes, this is the number of call minutes. For credits, this is the number of chat credits.
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="transfer" type="object">
  Details of the transfer

  <Expandable title="transfer properties">
    <ResponseField name="type" type="string">
      The transfer type: `minutes` or `credits`
    </ResponseField>

    <ResponseField name="operation" type="string">
      The operation: `add` or `remove`
    </ResponseField>

    <ResponseField name="amount" type="number">
      The amount transferred
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="user" type="object">
  The user's updated balance information

  <Expandable title="user properties">
    <ResponseField name="id" type="integer">
      The user's ID
    </ResponseField>

    <ResponseField name="email" type="string">
      The user's email
    </ResponseField>

    <ResponseField name="name" type="string">
      The user's name
    </ResponseField>

    <ResponseField name="minutes_balance" type="number">
      The user's current minutes balance
    </ResponseField>

    <ResponseField name="credits_balance" type="number">
      The user's current chat credits balance
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="your_balance" type="object">
  Your (tenant owner's) updated balance

  <Expandable title="your_balance properties">
    <ResponseField name="minutes" type="number">
      Your current minutes balance
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Minutes Transfer Success theme={null}
  {
    "message": "Transfer completed successfully.",
    "transfer": {
      "type": "minutes",
      "operation": "add",
      "amount": 100
    },
    "user": {
      "id": 123,
      "email": "user@example.com",
      "name": "John Doe",
      "minutes_balance": 150.5,
      "credits_balance": 0
    },
    "your_balance": {
      "minutes": 850.5
    }
  }
  ```

  ```json 200 Credits Transfer Success theme={null}
  {
    "message": "Transfer completed successfully.",
    "transfer": {
      "type": "credits",
      "operation": "add",
      "amount": 500
    },
    "user": {
      "id": 123,
      "email": "user@example.com",
      "name": "John Doe",
      "minutes_balance": 0,
      "credits_balance": 500
    },
    "your_balance": {
      "minutes": 944.44
    }
  }
  ```

  ```json 400 Insufficient Balance theme={null}
  {
    "error": "Insufficient minutes balance.",
    "available_balance": 50.5
  }
  ```

  ```json 400 User Insufficient Balance theme={null}
  {
    "error": "User has insufficient credits balance.",
    "user_credits_balance": 25
  }
  ```

  ```json 403 Not White Label Admin theme={null}
  {
    "error": "You are not a white label admin."
  }
  ```

  ```json 403 User Not In Platform theme={null}
  {
    "error": "User does not belong to your white label platform."
  }
  ```

  ```json 404 User Not Found theme={null}
  {
    "error": "User not found."
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "Either user_id or email is required.",
    "errors": {
      "user_id": ["Either user_id or email is required."],
      "email": ["Either user_id or email is required."]
    }
  }
  ```
</ResponseExample>

### Transfer Types

| Type      | Description                             | Conversion           |
| --------- | --------------------------------------- | -------------------- |
| `minutes` | Call minutes for AI phone calls         | Direct 1:1 transfer  |
| `credits` | Chat credits for AI chat, WhatsApp, SMS | 9 credits = 1 minute |

### Operations

| Operation | Minutes Behavior                        | Credits Behavior                                                  |
| --------- | --------------------------------------- | ----------------------------------------------------------------- |
| `add`     | Deducts from your balance, adds to user | Deducts minutes from you (at 9 credits/min), adds credits to user |
| `remove`  | Deducts from user, adds to your balance | Deducts credits from user, adds minutes to you                    |

### Example: Adding Credits to a User

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/white-label/transfer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "transfer_type": "credits",
    "operation": "add",
    "amount": 100
  }'
```

### Example: Removing Minutes from a User

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/white-label/transfer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 123,
    "transfer_type": "minutes",
    "operation": "remove",
    "amount": 50
  }'
```


# Building Flows
Source: https://docs.autocalls.ai/automation-platform/building-flows

Flow consists of two parts, trigger and actions

## Trigger

The flow's starting point determines its frequency of execution. There are various types of triggers available, such as Schedule Trigger, Webhook Trigger, or Event Trigger based on specific service.

## Action

Actions come after the flow and control what occurs when the flow is activated, like running code or communicating with other services.

In real-life scenario:

<img alt="Flow Parts" />


# Autocalls Tool
Source: https://docs.autocalls.ai/automation-platform/calls-related/autocalls-tool

Learn how to use Autocalls triggers and actions in your AI calling flows

# Autocalls Tool

The Autocalls tool is the core component that connects your AI calling system with automation flows. It enables real-time data exchange between your AI assistants and business systems, allowing for personalized conversations and automated follow-ups.

<Note>
  You can find the Autocalls tool prominently displayed at the top of the
  searching sidebar when looking for either triggers or actions.
</Note>

## Triggers

### Call Ended

<img alt="Autocalls Call Ended Trigger" />

The Call Ended trigger activates immediately after an AI call completes, providing comprehensive data about the interaction:

* Complete conversation transcript with timestamps
* AI assistant responses and decisions
* Call duration and technical metadata
* Customer information and phone number
* Call outcome and sentiment analysis
* Variables set during the conversation

#### Configuration

1. Select "Call Ended" as your trigger
2. Choose specific AI assistant to monitor
3. Configure variable mapping

### Inbound Call Variable Injection

This powerful trigger activates before your AI assistant picks up an inbound call, allowing you to:

* Fetch and inject real-time customer data
* Customize AI behavior based on context
* Set conversation parameters
* Define AI personality traits
* Provide business logic variables

#### Configuration

1. Select "Inbound Call" as your trigger
2. Define required variables for AI context

## Actions

### Add Lead to Campaign

<img alt="Autocalls Action" />

This action helps manage your AI calling campaigns by:

* Creating new leads from extenal tools like Sheets, Hubspot, Facebook leads
* Assigning leads to specific AI campaigns
* Adding context for future calls

#### Configuration

1. Select target AI campaign
2. Map contact details from trigger data
3. Add custom attributes for AI context

### Return Variables

This action is crucial for inbound calls, returning context that gets injected into the AI's prompt:

* Customer profile and preferences
* Conversation history summary
* Business rules and constraints
* Custom AI behavior flags
* Dynamic response templates

#### Configuration

1. Structure response JSON
2. Map customer data to variables
3. Set AI conversation parameters
4. Configure timeout handling

## Example Usage

### Post-Call Lead Management

```javascript theme={null}
Trigger: AI Call Ended
↓
Extract conversation insights
↓
Update Hubspot record
↓
Add to follow-up campaign if qualified
```

### Intelligent Inbound Routing

```javascript theme={null}
Trigger: Inbound Call to AI
↓
Fetch customer profile from CRM
↓
Get interaction history
↓
Return enriched context for AI prompt
```

## Best Practices

1. **Variable Injection Performance**

   * Keep processing under 2 seconds
   * Set sensible defaults

2. **Data Structure**

   * Follow AI prompt requirements
   * Validate all variables
   * Structure nested objects clearly
   * Document custom fields

3. **Error Handling**
   * Provide fallback values
   * Log injection failures
   * Monitor response times
   * Handle missing data gracefully


# Common Integrations
Source: https://docs.autocalls.ai/automation-platform/calls-related/common-integrations

Explore popular integrations with Google Sheets, calendars, CRMs, and notification tools

Below are some popular tools you can connect to Autocalls.ai using the built-in no-code platform or direct integrations:

## 1. Google Sheets

* **Import Leads**: Poll a sheet of phone numbers for an outbound campaign.
* **Log Call Results**: Append transcripts or call summaries to a "Call History" sheet.

## 2. Calendars (Cal.com, Google Calendar, etc.)

* **Appointment Scheduling**: The AI can suggest free slots, then create events.
* **Reminders**: If a call is about an upcoming appointment, the AI can confirm or reschedule.

## 3. HubSpot / CRMs

* **Lead Data**: Post-call info can be saved to a contact record.
* **Status Updates**: Change lead status to "Interested" or "Requires Follow-Up" automatically.

## 4. Slack / Email Notifications

* **Immediate Alerts**: If a user says "I want to cancel" or "I want to buy," trigger a Slack ping.
* **Daily Summary**: Email your team a daily summary of calls, outcomes, and new leads.

## 5. Others (Facebook Leads, etc.)

* Some advanced users integrate with Facebook Lead Ads or other marketing platforms to feed real-time leads into an Autocalls.ai outbound campaign.

***

**Tip:** In the Autocalls.ai automation editor, you'll see pre-built blocks for many popular tools. If something's missing, you can often use **Webhooks** or the **API** to connect.


# Sending SMS
Source: https://docs.autocalls.ai/automation-platform/calls-related/sms-capabilities

Learn how to send SMS messages using the automation platform and SMS-capable numbers

If your rented or custom-provisioned number supports SMS capabilities, you can leverage the automation platform to send text messages:

## 1. SMS Actions

* Send confirmation messages after calls
* Deliver follow-up information or links
* Send appointment reminders
* Provide quick updates or notifications

## 2. Configuration

1. Ensure your phone number is SMS-capable
2. Use the "Send SMS" action in your automation flow
3. Configure message template and variables
4. Set up triggers (e.g., after call completion)

## 3. Best Practices

* Keep messages concise and professional
* Include opt-out instructions if required by local laws
* Test SMS delivery before large campaigns
* Monitor delivery rates and costs

***

**Note:** SMS capability depends on your phone number's region and type. Contact support to confirm if your number supports texting.


# Debugging Runs
Source: https://docs.autocalls.ai/automation-platform/debugging-runs

Ensuring your business automations are running properly

You can monitor each run that results from an enabled flow:

1. Go to the Dashboard, click on **Runs**.
2. Find the run that you're looking for, and click on it.
3. You will see the builder in a view-only mode, each step will show a ✅ or a ❌ to indicate its execution status.
4. Click on any of these steps, you will see the **input** and **output** in the **Run Details** panel.

The debugging experience looks like this:

<img alt="Debugging Business Automations" />


# Introduction
Source: https://docs.autocalls.ai/automation-platform/introduction

Learn How to Automate Your AI Call Workflows with Autocalls

# Automation Platform

The Autocalls Automation Platform helps you create powerful AI call automation workflows without coding. Build flows that enhance your AI calling system by processing variables before calls, handling post-call actions, and creating seamless integrations with your existing tools.

<img alt="Flow Builder" />

## Key Features

### AI Call-Based Triggers

1. **Call Ended Trigger**

   * Activates immediately when an AI call completes
   * Access full conversation transcript and AI responses
   * Use call duration, status, and detailed metadata
   * Perfect for post-call automation like CRM updates
   * Trigger follow-up actions based on call outcomes

2. **Inbound Call Variable Injection**
   * Triggers before AI assistant picks up the call
   * Enriches AI context with real-time customer data
   * Customizes AI behavior based on caller information
   * Returns variables that get injected into AI prompts
   * Enables personalized conversation flows

### Essential Actions

1. **Hubspot Integration**

   * Update contact records with call outcomes
   * Create new contacts from inbound calls
   * Sync conversation insights to CRM
   * Track AI interaction history
   * Automate lead qualification

2. **Campaign Management**

   * Add qualified leads to AI calling campaigns
   * Schedule AI follow-up calls
   * Manage call priorities based on outcomes
   * Track conversion rates per campaign
   * Automate campaign assignments

3. **External Systems**
   * Send post-call summary emails
   * Update spreadsheets with call data
   * Trigger webhooks for custom integrations
   * Connect with your business tools
   * Automate multi-step workflows

## How It Works

1. **Choose Your Call Trigger**

   * "Call Ended" for post-conversation automation
   * "Inbound Call" for real-time AI context injection

2. **Configure Call Variables**

   * Map AI conversation data and transcripts
   * Access caller details and history
   * Define AI routing logic
   * Set up custom conversation variables

3. **Add Smart Actions**
   * Update CRM with call outcomes
   * Send automated notifications
   * Schedule follow-up activities
   * Return enriched context to AI

## Example Use Cases

### Intelligent CRM Update

```javascript theme={null}
Trigger: AI Call Ended
↓
Process Conversation Insights
↓
Update Hubspot Contact
↓
Schedule Next AI Interaction
```

### Smart Inbound Call Handling

```javascript theme={null}
Trigger: Inbound Call to AI
↓
Lookup Customer in Hubspot
↓
Return Enriched Context
↓
AI Assistant Personalizes Conversation
```


# Technical limits
Source: https://docs.autocalls.ai/automation-platform/known-limits

Technical limits for flows execution

### Overview

### Flow Limits

* **Execution Time**: Each flow has a maximum execution time of **600 seconds (10 minutes)**. Flows exceeding this limit will be marked as a timeout.
* **Memory Usage**: During execution, a flow should not use more than **128 MB of RAM**.

### File Storage Limits

* **Maximum File Size**: 10 MB

### Data Storage Limits

Some pieces utilize the built-in key store, such as the Store Piece and Queue Piece.

The storage limits are as follows:

* **Maximum Key Length**: 128 characters
* **Maximum Value Size**: 512 KB


# Passing Data
Source: https://docs.autocalls.ai/automation-platform/passing-data

Using data from previous steps in the current one

## Data flow

Any flow is a vertical diagram that **starts with a trigger step** followed by **any number of action steps**.

Steps are connected vertically. Data flows from parent steps to the children. Children steps have access to the output data of the parent steps.

## Example Steps

<video />

This flow has 3 steps, they can access data as follows:

* **Step 1** is the main data producer to be used in the next steps. Data produced by Step 1 will be accessible in Steps 2 and 3. Some triggers don't produce data though, like Schedules.

* **Step 2** can access data produced by Step 1. After execution, this step will also produce data to be used in the next step(s).

* **Step 3** can access data produced by Steps 1 and 2 as they're its parent steps. This step can produce data but since it's the last step in the flow, it can't be used by other ones.

## Data to Insert Panel

In order to use data from a previous step in your current step, place your cursor in any input, the **Data to Insert** panel will pop up.

<video />

This panel shows the accessible steps and their data. You can expand the data items to view their content, and you can click the items to insert them in your current settings input.

If an item in this panel has a caret (⌄) to the right, it means you can click on the item to expand its child properties. You can select the parent item or its properties as you need.

When you insert data from this panel, it gets inserted at the cursor's position in the input. This means you can combine static text and dynamic data in any field.

<video />

We generally recommend that you expand the items before inserting them to understand the type of data they contain and whether they're the right fit to the input you're filling.

## Testing Steps to Generate Data

We require you to test steps before accessing their data. This approach protects you from selecting the wrong data and breaking your flows after publishing them.

If a step is not tested and you try to access its data, you will see the following message:

<img alt="Test your automation step first" />

To fix this, go to the step and use the Generate Sample Data panel to test it. Steps use different approaches for testing. These are the common ones:

* **Load Data:** Some triggers will let you load data from your connected account without having to perform any action in that account.
* **Test Trigger:** Some triggers will require you to head to your connected account and fire the trigger in order to generate sample data.
* **Send Data:** Webhooks require you to send a sample request to the webhook URL to generate sample data.
* **Test Action:** Action steps will let you run the action in order to generate sample data.

Follow the instructions in the Generate Sample Data panel to know how your step should be tested. Some triggers will also let you Use Mock Data, which will generate static sample data from the piece. We recommend that you test the step instead of using mock data.

This is an example for generating sample data for a trigger using the **Load Data** button:

<video />

## Advanced Tips

### Switching to Dynamic Values

Dropdowns and some other input types don't let you select data from previous steps. If you'd like to bypass this and use data from previous steps instead, switch the input into a dynamic one using this button:

<video />

### Accessing data by path

If you can't find the data you're looking for in the **Data to Insert** panel but you'd like to use it, you can write a JSON path instead.

Use the following syntax to write JSON paths:

`{{step_slug.path.to.property}}`

The `step_slug` can be found by moving your cursor over any of your flow steps, it will show to the right of the step.


# Publishing Flows
Source: https://docs.autocalls.ai/automation-platform/publishing-flows

Make your flow work by publishing your updates

The changes you make won't work right away to avoid disrupting the flow that's already published. To enable your changes, simply click on the publish button once you're done with your changes.

<img alt="Flow Parts" />


# Cancel & Reschedule Cal.com Appointments
Source: https://docs.autocalls.ai/automation-platform/tutorials/cancel-reschedule-calcom

Learn how to create a mid-call tool that lets your AI assistant cancel or reschedule Cal.com bookings during live phone calls

This tutorial shows how to create a mid-call tool that allows your AI voice assistant to cancel or reschedule Cal.com bookings during a live phone conversation, using the Automation Platform.

<iframe title="Tutorial: Cancel & Reschedule Cal.com Appointments with AI Voice Assistant" />

## What You'll Learn

* Creating and configuring a custom mid-call tool with headers and parameters
* Building an automation flow that handles both cancellation and rescheduling via Cal.com API v2
* Understanding the difference between `/test` and `/sync` webhook endpoints
* Converting timezone-aware dates to UTC for the Cal.com API
* Writing AI prompt instructions so the assistant knows when and how to use the tool
* Testing the full flow end-to-end

## Prerequisites

* Autocalls.ai platform access
* Cal.com account with API key (v2)
* AI assistant already created and configured
* Phone number assigned for inbound or outbound calls

## Step 1: Create the Mid-Call Tool

We'll start by creating the tool that the assistant will call during live conversations. Later, we'll build the automation and come back to set the endpoint URL.

1. Go to **Mid Call Tools** in the sidebar
2. Click **New Mid Call Tool**
3. Configure the basic settings:
   * **Name**: `modify_booking` — must contain only lowercase letters, numbers, and underscores
   * **Description**: `Use this tool to cancel or reschedule a booking`
   * **Endpoint**: We'll fill this in after creating the automation (Step 5)
   * **Timeout**: `20` seconds
   * **Method**: POST

## Step 2: Add Headers

Add two headers to the tool:

| Header Name    | Value                                 |
| -------------- | ------------------------------------- |
| `Content-Type` | `application/json` (added by default) |
| `calApiKey`    | Your Cal.com API key                  |

To get your Cal.com API key:

1. Go to [cal.com](https://cal.com) and click **Go to App**
2. Navigate to **Settings → API Keys**
3. Click **Create new key**, check **Never expires**, give it a name (e.g., "Reschedule/Cancel booking")
4. **Save and copy** the key
5. Paste it as the value for the `calApiKey` header

The `calApiKey` header passes your Cal.com API key to the automation. The automation reads it from the webhook headers and uses it to authenticate all Cal.com API requests — keeping the key secure and out of the request body.

## Step 3: Configure Parameters

These are the values the AI assistant will extract from the conversation and send in the request body:

| Name                 | Type       | Description                                                                                   |
| -------------------- | ---------- | --------------------------------------------------------------------------------------------- |
| `email`              | String     | Email of the customer in the correct format. e.g: [john@example.com](mailto:john@example.com) |
| `cancellationReason` | String     | Reason of cancellation if customer wants to cancel                                            |
| `cancel_appt`        | True/False | TRUE only if the customer wants to cancel appointment. FALSE instead                          |
| `reschedule_appt`    | True/False | TRUE only if the customer wants to reschedule appointment. FALSE instead                      |
| `reschedule_reason`  | String     | The reason of reschedule                                                                      |
| `startDateTime`      | String     | The start date and time in ISO 8601 format for the new booking (e.g., 2025-01-14T15:00:00)    |

We use the `cancel_appt` and `reschedule_appt` boolean parameters to determine which branch the automation takes — cancel or reschedule.

<Note>
  **Timezone consideration:** If your assistant is set to a specific timezone (e.g., Europe/Bucharest), it will offer slots to the customer in that timezone. The customer picks a date and time, and we send it to the automation. Cal.com requires the date in UTC format — we'll handle the conversion in the automation using a Format Date step.
</Note>

<Tip>
  Parameter descriptions are critical. The AI reads them to understand what data to collect during the call and how to populate each field. Be specific about formats and when each parameter applies.
</Tip>

Save the tool for now. We'll come back to set the endpoint URL once we create the automation.

## Step 4: Create the Automation Flow

Now we'll build the automation that receives data from the mid-call tool, interacts with Cal.com's API, and returns the result.

1. Go to **Automation Platform** by clicking "Automate platform" in the sidebar
2. Click **New Flow** and select **From Scratch**
3. Search for **Webhook** and select **Catch Webhook** as your trigger
4. Copy the generated webhook URL
5. Click **Test** to start listening for incoming data

## Step 5: Set the Tool Endpoint

Now go back to the mid-call tool you created in Step 1:

1. Paste the webhook URL into the **Endpoint** field
2. Add `/test` at the end — e.g.: `https://your-webhook-url.com/api/v1/webhooks/abc123.../test`
3. **Save** the tool
4. Click **Test Tool** in the mid-call tool page — you should see the test data arrive in the automation platform

<Warning>
  **`/test` vs `/sync` — Important:**

  * **`/test`** — Use during development. The automation platform captures sample data when you click "Test Flow". The tool won't receive a meaningful response back.
  * **`/sync`** — Use in production. This mode waits for the Return Response step and sends the actual result back to the AI assistant.

  Always start with `/test` for building and debugging, then switch to `/sync` when going live.
</Warning>

## Step 6: Fetch the Customer's Upcoming Bookings

Back in the automation flow, add the first action step after the webhook trigger.

1. Click **+** to add an action
2. Search for **HTTP** and select **Send HTTP Request**
3. Configure the request:

| Field      | Value                             |
| ---------- | --------------------------------- |
| **Method** | GET                               |
| **URL**    | `https://api.cal.com/v2/bookings` |

4. Add these **headers**:

| Header Name       | Value                                             |
| ----------------- | ------------------------------------------------- |
| `Authorization`   | Select from Catch Webhook → Headers → `calApiKey` |
| `cal-api-version` | `2024-08-13`                                      |

5. Add these **query parameters**:

| Parameter       | Value                                      |
| --------------- | ------------------------------------------ |
| `status`        | `upcoming`                                 |
| `attendeeEmail` | Select from Catch Webhook → Body → `email` |

This fetches all upcoming bookings for the customer's email. You can also filter by name if you don't need email.

<Tip>
  **Testing tip:** To verify this step works, temporarily hardcode your own email in the `attendeeEmail` query parameter, create a test booking on your Cal.com public page, then click "Test Step". Once you see the booking returned successfully, replace the hardcoded email with the dynamic value from the webhook body.
</Tip>

## Step 7: Add Branch Logic — Cancel or Reschedule?

We need to route the flow based on what the customer requested.

1. Click **+** and search for **Branch**
2. Set the first value: Select from Catch Webhook → Body → `cancel_appt`
3. Set the condition: **Boolean is True**

This creates two paths:

* **True branch** → Customer wants to cancel
* **False branch** → We check for reschedule next

4. On the **False branch**, add another **Branch** step
5. Set the first value: Select from Catch Webhook → Body → `reschedule_appt`
6. Set the condition: **Boolean is True**

If this is true, the customer wants to reschedule the appointment.

## Step 8: Build the Reschedule Branch (True side of second Branch)

### 8a: Format the Date to UTC

Since Cal.com requires the date in UTC format, we first need to convert it.

1. On the **True path** of the reschedule branch, click **+** and search for **Format Date**
2. Configure:
   * **Input:** Select from Catch Webhook → Body → `startDateTime`
   * **From Format:** ISO format
   * **From Timezone:** Your assistant's timezone (e.g., `Europe/Bucharest`)
   * **To Format:** ISO format
   * **To Timezone:** `UTC` (GMT)
3. **Test** to verify the conversion works correctly

### 8b: Call the Reschedule API

1. Add an **HTTP Request** step after Format Date:

| Field      | Value                                                     |
| ---------- | --------------------------------------------------------- |
| **Method** | POST                                                      |
| **URL**    | `https://api.cal.com/v2/bookings/{bookingUid}/reschedule` |

For the `{bookingUid}` part, delete it and insert the UID from the Get Bookings step: select **Send HTTP Request → Body → data → 0 → uid**

2. Add these **headers**:

| Header Name       | Value                                             |
| ----------------- | ------------------------------------------------- |
| `Content-Type`    | `application/json`                                |
| `cal-api-version` | `2024-08-13`                                      |
| `Authorization`   | Select from Catch Webhook → Headers → `calApiKey` |

3. Set **Body** type to JSON and enter:

```json theme={null}
{
  "start": "{{format_date_step.result}}",
  "reschedulingReason": "{{trigger.body.reschedule_reason}}"
}
```

Replace `format_date_step.result` with the actual output from the Format Date step (select it from the dynamic values panel), and `trigger.body.reschedule_reason` with the value from the webhook body.

<Warning>
  Make sure you don't leave a trailing comma at the end of the JSON body — this will cause a parsing error.
</Warning>

### 8c: Return Response

1. Add a **Return Response** step (search for Webhook → Return Response)
2. Click on the body field, select dynamic value
3. Delete the `{}` and insert the full body from the reschedule HTTP request step

This sends the reschedule result back to the AI assistant via the `/sync` endpoint.

## Step 9: Build the Cancel Branch (True side of first Branch)

1. On the **True path** of the first branch, add an **HTTP Request** step:

| Field      | Value                                                 |
| ---------- | ----------------------------------------------------- |
| **Method** | POST                                                  |
| **URL**    | `https://api.cal.com/v2/bookings/{bookingUid}/cancel` |

For `{bookingUid}`, insert the UID from the Get Bookings step: **Send HTTP Request → Body → data → 0 → uid**

2. Add these **headers**:

| Header Name       | Value              |
| ----------------- | ------------------ |
| `Content-Type`    | `application/json` |
| `cal-api-version` | `2024-08-13`       |

3. Set **Body** type to JSON:

```json theme={null}
{
  "cancellationReason": "{{trigger.body.cancellationReason}}"
}
```

Select the `cancellationReason` value from Catch Webhook → Body → `cancellationReason`.

4. Add a **Return Response** step after the cancel request
5. Click on the body field, select dynamic value, delete the `{}`, and insert the full body from the cancel HTTP request step

This tells the AI assistant whether the cancellation was successful or not.

## Step 10: Publish and Switch to /sync

1. **Verify** all steps are correctly configured
2. Click **Publish** to make the flow live
3. Go back to your mid-call tool and change the endpoint from `/test` to `/sync`
4. **Save** the tool

Now the tool will wait for the automation's Return Response and send the actual Cal.com response back to the AI assistant during the call.

## Step 11: Attach the Tool to Your Assistant

1. Navigate to your AI assistant
2. Go to **Prompts and Tools** tab
3. In the **Custom Tools** section, attach the `modify_booking` tool
4. **Save** the assistant

Also make sure you have **Cal.com Appointment Scheduling** connected in the assistant settings with your API key and event selected — this enables the assistant to also book new appointments, not just cancel or reschedule.

As for call variables, you can place the `email` variable here with a default value. During a real call, if the customer's email isn't available as a variable, the assistant will need to ask for it during the conversation — make sure your prompt instructs it to do so.

## Step 12: Configure the AI Prompt

Open the **AI Prompt Editor** to instruct the AI on when and how to use the tool. You can type natural language instructions and let the editor generate the prompt rules for you.

Example instructions to give the AI Prompt Editor:

```
If the customer wants to cancel or reschedule an appointment:
1. First ask for their email address
2. For reschedule: call the get_slots tool first to check available times, then call modify_booking with the chosen slot
3. For cancel: ask for cancellation reason, then call modify_booking
4. Always confirm the action with the customer before proceeding
```

The AI Prompt Editor will generate the appropriate system prompt rules. Review them, click **Accept**, then **Save**.

<Tip>
  If you're using the Web Widget and the customer's phone number or email isn't automatically available, add instructions in the system prompt to request that information during the conversation.
</Tip>

## Step 13: Test End-to-End

### Using Test Assistant (Chat)

1. Click **Test Assistant** to open the chat test interface
2. Start a conversation and try booking an appointment first
3. Then ask to reschedule or cancel — the assistant should ask for your email, and proceed with the appropriate action

<Note>
  In the test chat, the assistant may ask for a phone number since it's not a real call. For web widget usage, add phone/email collection instructions to the system prompt.
</Note>

### Using Speak to Assistant (Voice)

1. Click **Speak to Assistant** for a live voice test
2. Request a cancellation or reschedule during the conversation
3. Check the automation platform to verify the flow executed correctly and the correct branch was taken

### Production Testing

Make a real phone call to your assistant's number and test the full cancel/reschedule flow with actual Cal.com bookings.

## Best Practices

### Tool Configuration

* **Use descriptive parameter descriptions** — the AI relies on these to extract the right data from the conversation
* **Set timeout to 20 seconds** — the flow involves multiple API calls (get bookings + cancel/reschedule)
* **Always use `/sync` in production** — otherwise the AI won't receive the response data

### Prompt Design

* **Request email early** — the tool needs it for the Cal.com booking lookup
* **For reschedule: use get\_slots first** — have the AI check available times before calling the reschedule tool
* **Handle edge cases** — what if the customer doesn't know their email? What if no upcoming bookings are found? Add instructions for these scenarios

### Security

* **Pass API keys via headers** — not in the request body or parameters
* **Never expose keys** in parameter descriptions or prompt instructions

## Troubleshooting

### Common Issues

**Tool returns empty response:**

* Make sure you're using `/sync` not `/test` in production
* Verify the Return Response step is configured in your flow
* Check that the flow is published

**AI doesn't use the tool:**

* Review the tool description — it must clearly indicate when to use it
* Check that the tool is attached to the correct assistant
* Verify your prompt includes explicit instructions about when to call the tool

**Cal.com API returns errors:**

* Confirm your API key is valid and has the correct permissions
* Check the `cal-api-version` header matches (`2024-08-13`)
* Verify the booking UID exists and status is "upcoming"

**Wrong timezone for rescheduled appointment:**

* Make sure the Format Date step converts from your assistant's timezone to UTC
* Verify the "From Timezone" matches your assistant's configured timezone

**Wrong branch is taken:**

* Ensure `cancel_appt` and `reschedule_appt` are True/False type parameters, not strings
* Check that Branch conditions use "Boolean is True" operator

## Next Steps

Once your cancellation and rescheduling flow is working:

* **Send confirmation SMS** — add a post-action SMS step using [SMS automation](/automation-platform/calls-related/sms-capabilities)
* **Log actions to Google Sheets** — track all cancellations and reschedules using [Google Sheets sync](/automation-platform/tutorials/google-sheets-sync)
* **Add email notifications** — send confirmation emails with [Post-Call Email Automation](/automation-platform/tutorials/post-call-email-automation)
* **Handle multiple bookings** — modify the flow to let the customer choose which booking to modify if they have more than one


# GoHighLevel Leads Automation
Source: https://docs.autocalls.ai/automation-platform/tutorials/gohighlevel-leads-automation

Learn how to automatically call GoHighLevel leads with AI voice agents

This tutorial shows how to set up an automation that automatically calls new leads from GoHighLevel using AI voice agents with intelligent retry logic.

<iframe title="Tutorial: How to call Go High Level leads with AI voice agents automatically" />

## What You'll Learn

* Creating an AI assistant with custom call variables
* Setting up GoHighLevel integration with LeadConnector
* Configuring campaigns with retry logic and goal completion
* Mapping lead data from GoHighLevel to your assistant
* Testing and deploying your automation flow

## Prerequisites

* Active GoHighLevel account
* Autocalls.ai platform access
* Phone number configured for outbound calls

## Step 1: Create Your AI Assistant

First, we need to create an AI assistant that will handle the calls to your GoHighLevel leads.

<Frame>
  <img alt="Creating new AI assistant" />
</Frame>

1. **Navigate to Assistants page** and click on "Assistants" in the sidebar
2. **Click "New Assistant"** button to start the creation process
3. **Give it a name** - for this tutorial, we'll use "Test ghl"

<Frame>
  <img alt="Assistant basic settings configuration" />
</Frame>

4. **Select a phone number** for outbound calls
5. **Choose a voice** that fits your brand
6. **Set the timezone** for your target audience

## Step 2: Configure Call Variables

Call variables allow you to personalize each call with specific lead information from GoHighLevel.

<Frame>
  <img alt="Navigating to Prompts and Tools tab" />
</Frame>

1. **Go to the second tab** "Prompts and Tools"
2. **Locate the "Call Variables" section**

<video />

3. **Add custom variables** for your GoHighLevel leads:
   * You'll see `customer_name` with default value "John"
   * **Add `email` variable** with a default value
   * Add any additional variables like `company_name`, `address`, etc.

4. **Variables can be used in multiple ways:**
   * **In the system prompt**: "Hi `{customer_name}`"
   * **For mid-call tools**: Personalized API calls
   * **For file imports**: Bulk lead processing
   * **For automation platform**: Dynamic data mapping

## Step 3: Set Up Post-Call Variables

Post-call variables help track the success of your calls and automate follow-up actions.

<Frame>
  <img alt="Post-call variables configuration" />
</Frame>

1. **Navigate to step 3** "Post-call Variables"
2. **Review the default variables:**
   * `status` - Boolean (true/false) indicating if call objective was achieved
   * `summary` - Text summary of the call conversation

<Frame>
  <img alt="Understanding the status variable" />
</Frame>

The `status` variable is crucial for campaign automation:

* **True**: Call objective achieved, lead marked as completed
* **False**: Call objective not met, lead will be retried

3. **Click "Create"** to finalize your assistant

## Step 4: Create Campaign with Retry Logic

Now we'll create a campaign that intelligently retries leads until the call objective is achieved.

<Frame>
  <img alt="Creating new campaign" />
</Frame>

1. **Navigate to Campaigns** page in the sidebar
2. **Click "New Campaign"** button

<video />

3. **Configure campaign settings:**
   * **Give your campaign a name**
   * **Select the assistant** you just created

4. **Click "Create"** to save your campaign

## Step 5: Set Up GoHighLevel Integration

Now we'll create the automation that imports leads from GoHighLevel into your campaign.

<video />

1. **Click "Automate platform"** in the sidebar
2. **Press "New Flow"** and select "From Scratch"

<video />

3. **Search for "LeadConnector"** in the trigger search bar
4. **Click on LeadConnector** when it appears

<Frame>
  <img alt="Selecting new contact trigger" />
</Frame>

5. **Select "New Contact"** trigger
   * This will trigger for each new lead created in GoHighLevel

## Step 6: Connect Your GoHighLevel Account

<video />

1. **Click "New Connection"** to link your GoHighLevel account
2. **Give the connection a name** (e.g., "My GoHighLevel Account")

<video />

3. **Click "Connect"** to start OAuth authorization

4. **Authorize the connection** in the popup window:
   * Scroll down and click "Next"
   * Select your desired GoHighLevel account
   * Complete the authorization process

5. **Click "Save"** to finalize the connection

## Step 7: Test the Trigger with Sample Data

Before we can configure the automation, we need sample lead data to work with.

<video />

1. **Go to your GoHighLevel account**
2. **Navigate to Contacts** page
3. **Click the "+" button** to create a new contact
4. **Fill in test data:**
   * First name, last name
   * Email address
   * Phone number
5. **Click "Save"** to create the contact

<video />

6. **Return to the automation platform**
7. **Click "Load Data"** to fetch the test contact
8. **Verify the contact data** appears correctly

## Step 8: Configure the Campaign Action

Now we'll set up the action that adds leads to your calling campaign.

<video />

1. **Click the "+" sign** to add an action step
2. **Search for your calling platform**
3. **Select "Add Lead to Campaign"** action
4. **Select the campaign** you created earlier

## Step 9: Map Lead Data to Call Variables

This is where we connect GoHighLevel lead data to your assistant's call variables.

<Frame>
  <img alt="Mapping phone number from trigger data" />
</Frame>

1. **Click on the "Phone Number" input field**
2. **Select the phone number** from the trigger data sidebar
3. **Click "Insert"** to map the field

<video />

4. **Map the call variables** you defined in your assistant:
   * **customer\_name**: Use both "first\_name" and "last\_name"
   * **email**: Map to the email field from GoHighLevel

<Frame>
  <img alt="Completed variable mapping" />
</Frame>

5. **Add additional variables** using "Add Item" if you have more custom fields

<Tip>
  Always define variables in your assistant first, then map them in the automation. This ensures proper data flow from GoHighLevel to your calls. Learn more about [configuring call variables](/ai-assistants/settings/prompt-and-tools#call-variables).
</Tip>

## Step 10: Test and Deploy

<video />

1. **Click "Test Step"** to verify the lead is added correctly
2. **Check the confirmation** that the customer was added

<Frame>
  <img alt="Verifying lead in platform" />
</Frame>

3. **Navigate to the Leads page** to verify:
   * The lead appears in your platform
   * Variables are imported correctly
   * Data matches your GoHighLevel contact

<Frame>
  <img alt="Publishing the automation" />
</Frame>

4. **Return to automation and click "Publish"**
   * Your automation is now live
   * Every new GoHighLevel contact will be automatically added

## Step 11: Start Your Campaign

1. **Go to Campaigns page**
2. **Click the "Start" button** on your campaign
3. **Your leads will now be called automatically** based on your retry settings

## Best Practices

### Variable Management

* **Define all necessary variables** in your assistant before creating automations
* **Use descriptive variable names** that match your GoHighLevel fields
* **Test with sample data** before going live

### Campaign Configuration

* **Start with 3 retries maximum** to avoid overwhelming leads
* **Use 60-minute intervals** to allow reasonable callback timing
* **Monitor the `status` variable** to track conversion rates

### Lead Quality

* **Ensure phone numbers are in international format** (+1234567890)
* **Verify email addresses** for follow-up automations
* **Keep lead data up to date** in GoHighLevel

## Troubleshooting

### Common Issues

**Leads not being imported:**

* Check GoHighLevel connection authorization
* Verify webhook is properly configured
* Ensure new contacts have valid phone numbers

**Variables not populating:**

* Confirm variable names match between assistant and automation
* Check that GoHighLevel fields contain data
* Verify mapping in the automation step

**Calls not triggering:**

* Ensure campaign is started
* Check phone number configuration
* Verify assistant is properly configured

## Next Steps

Once your basic automation is working:

* **Set up SMS follow-ups** for unsuccessful calls
* **Create Google Sheets integration** to track qualified leads
* **Add email automation** for additional touchpoints
* **Monitor and optimize** your conversion rates

Your GoHighLevel leads will now be automatically called by your AI assistant with intelligent retry logic until your call objectives are achieved!


# Sync Qualified Leads to Google Sheets
Source: https://docs.autocalls.ai/automation-platform/tutorials/google-sheets-qualified-leads

Learn how to automatically add qualified leads to Google Sheets after successful AI phone calls

This tutorial shows how to set up an automation that automatically adds qualified leads to a Google Sheet after successful AI phone calls, creating a powerful lead tracking and CRM system.

<iframe title="Tutorial: How to sync qualified leads in a live Google Sheet" />

## What You'll Learn

* Setting up post-call automation with conditional logic
* Creating Google Sheets integration for lead tracking
* Configuring data mapping from calls to spreadsheet
* Building a qualified leads database automatically
* Monitoring and optimizing your lead collection process

## Prerequisites

* Configured AI assistant with post-call variables
* Google account with Google Sheets access
* Understanding of post-call webhook automation
* Access to call testing functionality

## Step 1: Set Up Post-Call Automation Trigger

We'll start by creating an automation that triggers when a phone call ends.

<video />

1. **Navigate to Automation Platform**
2. **Create a new flow** from scratch
3. **Search for your calling platform** in the trigger section
4. **Select "Phone Call Ended"** trigger
   * This trigger activates when any call to your selected assistant completes

## Step 2: Configure Assistant and Load Data

<video />

1. **Select the assistant** you want to automate
   * Each assistant can only have one "phone call ended" automation
   * All calls to this assistant will go through this automation
2. **Click "Load Data"** to set up the webhook and load sample call data
   * This automatically configures the webhook on your assistant
   * Sample data from your recent calls will be loaded for use in the next steps

## Step 3: Verify Assistant Variables

Before proceeding, make sure your assistant has the right variables configured:

1. **Check post-call variables** in your assistant's "Post-call Actions" tab:
   * **status**: Boolean (true/false) indicating if call objective was achieved
   * **summary**: Text summary of the call conversation
   * These variables are extracted by AI after each call

<Frame>
  <img alt="Post-call variables configuration" />
</Frame>

### Adding New Post-Call Variables

If you add a new post-call variable after creating the automation:

1. **Define the new variable** in your assistant's "Post-call Actions" tab and save
2. **Return to your automation** and click **"Load Data"** again to refresh the available fields
3. **Re-evaluate an existing call** if needed to extract the new variable from past calls

## Step 4: Add Conditional Logic for Qualified Leads

We only want to add leads to Google Sheets when the call objective was achieved.

<video />

1. **Click the "+" sign** to add a step
2. **Search for "Branch"** in control flow
3. **Select Branch** to create conditional logic

<video />

4. **Configure the branch condition:**
   * **Select `status` variable** from call data
   * **Choose "Boolean is true"**
   * This creates two paths: True (qualified) and False (not qualified)

## Step 5: Create Google Sheets Integration

Now we'll set up the Google Sheets action for qualified leads (True branch).

<video />

1. **On the True branch**, click the "+" sign
2. **Search for "Google Sheets"**
3. **Select "Insert Row"** action

<video />

4. **Create a new Google Sheets connection:**
   * Authorize with your Google account
   * Save the connection for future use

## Step 6: Set Up Your Qualified Leads Spreadsheet

<video />

1. **Create a new Google Sheet** named "successful calls" for example

2. **Set up column headers:**
   * **Column A**: `phone_number`
   * **Column B**: `summary`
   * Add more columns for additional data as needed

## Step 7: Configure Spreadsheet Selection

<video />

1. **Return to your automation**
2. **Select your "successful calls" spreadsheet**
3. **Select the correct sheet** (usually "Sheet1")

<video />

4. **Enable "First row contains headers"**:
   * This tells the automation about your column structure
   * Headers should automatically load and display

## Step 8: Map Call Data to Spreadsheet Columns

<video />

1. **Map the phone number:**
   * Click on the `phone_number` field
   * **Select "Phone Call Ended"** data source
   * **Find and select the phone number** from call data
   * Click "Insert"

<video />

2. **Map the call summary:**
   * Click on the `summary` field
   * **Navigate to "Post Call Variables"**
   * **Select the `summary` variable**
   * Click "Insert"

3. **Map any additional fields:**
   * Email from call variables
   * Call date/time from call metadata
   * Any custom variables you've defined

## Step 9: Test and Verify

<video />

1. **Click "Test Step"** to verify the integration
2. **Check for successful execution**
3. **Go to your Google Sheet** to confirm:
   * New row was added with correct data
   * All mapped fields populated properly
   * Data formatting looks correct

## Step 10: Publish and Monitor

<Frame>
  <img alt="Publishing the automation" />
</Frame>

1. **Click "Publish"** to activate your automation
2. **Your qualified leads tracking is now live**
3. **Monitor automation performance:**
   * Check automation "Runs" for execution history
   * Verify qualified leads are being added to your sheet
   * Monitor for any failed executions

## Troubleshooting

### Common Issues

**Leads not appearing in spreadsheet:**

* Verify Google Sheets connection is authorized
* Check that automation is published and active
* Confirm calls are triggering `status` = `true`
* Verify branch condition is configured correctly

**Incomplete data in spreadsheet:**

* Check all field mappings in the automation
* Verify post-call variables are being extracted
* Confirm spreadsheet headers match automation fields
* Test with various call scenarios

## Next Steps

Once your qualified leads automation is working:

* **Add lead scoring** based on call quality
* **Create follow-up automations** for hot leads
* **Integrate with email marketing** platforms
* **Set up analytics dashboards** for conversion tracking
* **Expand to multiple campaigns** and lead sources

Your qualified leads will now be automatically captured and organized in Google Sheets, creating a powerful foundation for your sales and follow-up processes!


# Google Sheets Live Sync
Source: https://docs.autocalls.ai/automation-platform/tutorials/google-sheets-sync

Learn how to sync leads from a live Google Sheet and trigger AI calls automatically

This tutorial shows how to set up an automation that monitors a Google Sheet for new leads and automatically triggers AI calls when new rows are added.

<iframe title="Tutorial: How to sync leads from a live Google Sheet" />

## What You'll Learn

* Creating an AI assistant optimized for Google Sheets integration
* Setting up Google Sheets trigger for new row additions
* Configuring proper data mapping from spreadsheet to assistant
* Testing and deploying your live sync automation
* Best practices for spreadsheet formatting

## Prerequisites

* Google account with Google Sheets access
* Phone number configured for outbound calls
* Basic understanding of spreadsheet structure

## Step 1: Create Your AI Assistant

We'll start by creating an AI assistant specifically configured for Google Sheets lead processing.

<Frame>
  <img alt="Creating new AI assistant for Google Sheets" />
</Frame>

1. **Navigate to Assistants page** and click "Assistants" in the sidebar
2. **Click "New Assistant"** button
3. **Name your assistant** - we'll use "Test GoogleSheets"

<video />

4. **Complete the basic settings:**
   * Select a phone number for outbound calls
   * Choose an appropriate voice
   * Set your timezone

## Step 2: Configure Call Variables for Spreadsheet Data

Call variables will map directly to columns in your Google Sheet, so plan your spreadsheet structure accordingly.

<Frame>
  <img alt="Navigating to Prompts and Tools tab" />
</Frame>

1. **Go to the "Prompts and Tools" tab** (second tab)
2. **Locate the "Call Variables" section**

<video />

3. **Configure your call variables:**
   * You'll see `customer_name` with default value "John"
   * **Add `email` variable** with your email as default value for testing
   * Add any additional variables that match your spreadsheet columns

4. **Variables can be used in multiple ways:**
   * **In the system prompt**: "Hi `{customer_name}`"
   * **For mid-call tools**: Personalized API calls
   * **For file imports**: Bulk lead processing
   * **For automation platform**: Dynamic data mapping

## Step 3: Create Campaign for Sheet Leads

<Frame>
  <img alt="Creating campaign for Google Sheets leads" />
</Frame>

1. **Navigate to Campaigns** page in the sidebar
2. **Click "New Campaign"** button

<video />

3. **Configure your campaign:**
   * **Give it a descriptive name**
   * **Select the assistant** you just created
   * **Keep default retry settings** (can be adjusted later)

4. **Click "Create"** to save the campaign

## Step 4: Set Up Google Sheets Automation

Now we'll create the automation that monitors your Google Sheet for new leads.

<video />

1. **Click "Automation Platform"** in the sidebar
2. **Create a new flow** from scratch

<video />

3. **Search for "Google Sheets"** in the trigger search
4. **Select "New Row Added"** trigger

<video />

5. **Create a new connection:**
   * Click "New Connection"
   * Authorize with your Google account
   * Click "Save" once connected

## Step 5: Create and Configure Your Test Spreadsheet and add sample data

For this tutorial, we'll create a properly formatted test spreadsheet.

<video />

1. **Go to Google Sheets** and create a new spreadsheet
2. **Name it "testnewleads"** (or any descriptive name)
3. **Add a test lead in the first row:**
   * **Phone number**: Use international format (+1234567890)
   * **Customer name**: Your name for testing
   * **Email**: Your email address

<Warning>
  **Phone Number Format**: Always use international format with + sign and no spaces or parentheses. Example: +1234567890, not (123) 456-7890
</Warning>

2. **Save the spreadsheet** - this data will be used for testing

## Step 7: Configure the Automation Trigger

<video />

1. **Return to the automation platform**
2. **Select your spreadsheet** ("testnewleads")
3. **Select the specific sheet** (usually "Sheet1")

<video />

4. **Click "Load Data"** to fetch the sample lead
5. **Verify** that you can see the lead data you just created

## Step 8: Configure the Campaign Action

<video />

1. **Click the "+" sign** to add an action
2. **Search for your calling platform**
3. **Select "Add Lead to Campaign"**

<video />

4. **Select the campaign** you created for this automation

## Step 9: Map Spreadsheet Data to Assistant Variables

This step connects your spreadsheet columns to your assistant's call variables.

<video />

1. **Click on the "Phone Number" input field**
2. **A sidebar will open** showing available data from the trigger
3. **Search for and select the phone number** from your spreadsheet
4. **Click "Insert"** to map the field

<video />

5. **Map your call variables:**
   * **customer\_name**: Select from spreadsheet data
   * **email**: Select from spreadsheet data
   * Map any additional variables you defined

<Tip>
  The variable names in your assistant must match the data you're mapping. If you have more columns in your spreadsheet, make sure to define corresponding variables in your assistant first. Learn more about [configuring call variables](/ai-assistants/settings/prompt-and-tools#call-variables).
</Tip>

## Step 10: Test the Integration

<video />

1. **Click "Test Step"** to verify the lead creation
2. **Check for success confirmation**
3. **Navigate to your Leads page** to confirm:
   * The lead appears in your platform
   * All variables are correctly populated
   * Data matches your spreadsheet entry

## Step 11: Publish and Monitor

<Frame>
  <img alt="Publishing the automation" />
</Frame>

1. **Click "Publish"** to activate your automation
2. **Your spreadsheet is now being monitored** for new rows
3. **Test the live sync:**
   * Add new leads to your spreadsheet
   * Check that they automatically appear in your platform
   * Monitor the automation runs for any issues
4. **Monitor automation performance:**
   * Click "Runs" button in your automation
   * Review each execution for success/failure
   * Check timing and data accuracy

## Best Practices

### Spreadsheet Management

* **Maintain consistent data format** across all entries
* **Keep phone numbers in international format** consistently
* **Avoid empty rows** between data entries

## Advanced Features

### Multiple Variable Support

If your business needs more lead data:

1. **Add columns** to your spreadsheet (company\_name, address, etc.)
2. **Define corresponding variables** in your assistant
3. **Map the new fields** in your automation
4. **Test with sample data** before adding real leads

## Troubleshooting

### Common Issues

**Leads not syncing:**

* Check Google Sheets connection authorization
* Verify spreadsheet permissions and sharing settings
* Ensure new rows contain data in all mapped columns

**Phone number format errors:**

* Use international format: +1234567890
* Remove spaces, parentheses, and dashes
* Verify country code is included

**Variable mapping issues:**

* Confirm variable names match between assistant and spreadsheet
* Check that columns contain data
* Verify mapping configuration in automation

**Automation not triggering:**

* Ensure automation is published and active
* Check that new rows are actually being added
* Verify Google Sheets trigger is properly configured

## Next Steps

Once your Google Sheets integration is working:

* **Scale up** with larger lead lists
* **Add more variables** for better personalization
* **Integrate with other tools** like CRM systems
* **Set up follow-up automations** for call results
* **Monitor and optimize** your conversion rates

Your Google Sheet is now a powerful lead management tool that automatically triggers AI calls for every new lead you add!


# Inbound Call Context Injection
Source: https://docs.autocalls.ai/automation-platform/tutorials/inbound-context-injection

Learn how to enrich your AI assistant with real-time customer data

# Inbound Call Context Injection

This tutorial demonstrates how to enhance your AI assistant's conversations by injecting real-time context before the call connects.

<iframe title="Tutorial: Inbound Call Context Injection" />

## What You'll Learn

* Setting up the Inbound Call trigger
* Fetching lates product data from WooCommerce
* Structuring context for the AI

## Prerequisites

* Autocalls account with inbound numbers
* WooCommerce integration
* AI assistant configured for context injection


# Mid-Call Order Lookup from Google Sheets
Source: https://docs.autocalls.ai/automation-platform/tutorials/mid-call-google-sheets-lookup

Learn how to look up order data from Google Sheets during a live call using mid-call tools and the automation platform

This tutorial shows how to create a mid-call tool that connects to the automation platform to look up order information from a Google Sheet in real-time during calls. When a customer asks about their order, the AI assistant searches for their phone number in your spreadsheet and retrieves the order details to provide accurate information.

<iframe title="Tutorial: Mid-Call Order Lookup from Google Sheets" />

## What You'll Learn

* Creating an automation flow with a webhook trigger and Google Sheets lookup
* Setting up a mid-call tool that connects to the automation platform
* Handling phone number format differences between the tool and Google Sheets
* Looking up order data by customer phone number during a live call
* Using the AI Prompt Editor to configure your assistant's behavior

## Prerequisites

* Google account with Google Sheets access
* AI assistant configured for calls
* Basic understanding of [custom mid-call tools](/ai-assistants/custom-tools)
* Access to the [automation platform](/automation-platform/introduction)

## How It Works

Before we start, here's the big picture of what we're building:

```
Customer asks about order → AI triggers mid-call tool with customer_phone
→ Automation strips "+" from phone number → Looks up row in Google Sheets
→ Returns order details → AI tells the customer their order status
```

The key concept is using the automation platform as a **middleware** between your mid-call tool and Google Sheets. The mid-call tool calls the automation webhook synchronously (with `/sync`), the automation searches your spreadsheet, and returns the data back to the AI in real-time.

## Step 1: Prepare Your Google Sheet

First, set up a Google Sheet with your order data. The AI will search this sheet by phone number during calls.

1. **Create a new Google Sheet**
2. **Set up your columns** — for example:

| customer\_phone | customer\_name | order\_number | order\_status | product             |
| --------------- | -------------- | ------------- | ------------- | ------------------- |
| 1234567890      | John Smith     | ORD-1001      | Shipped       | Smart Watch         |
| 0987654321      | Jane Doe       | ORD-1002      | Processing    | Wireless Headphones |

3. **Add a test row** with your own phone number so you can test later
4. **Rename the spreadsheet** to something descriptive (e.g., "Orders AI")

<Warning>
  **Phone number format**: Google Sheets doesn't allow a `+` sign in front of numbers. Store phone numbers **without** the `+` prefix (e.g., `1234567890` instead of `+1234567890`). We'll handle stripping the `+` in the automation flow.
</Warning>

## Step 2: Create the Automation Flow

Now we'll build the automation that receives a phone number from the mid-call tool, searches Google Sheets, and returns the order data.

1. Navigate to the **Automation Platform** by clicking "Automate platform" in the sidebar
2. Click **New Flow** and select **From Scratch**
3. Search for **Webhook** and select **Catch Webhook** as your trigger
4. A live URL will be generated — **copy it**

<Note>
  Don't close this tab. We'll come back to test the trigger after setting up the mid-call tool.
</Note>

## Step 3: Create the Mid-Call Tool

Open a new tab and navigate to **Mid Call Tools** to create the tool that will call our automation webhook.

1. Click **New Mid Call Tool**
2. Fill in the tool details:
   * **Name**: `get_order_status`
   * **Description**: `Look up order information using the customer_phone variable from the call. Use this tool when a customer asks about their order status, delivery, or purchase history.`
   * **Endpoint**: Paste the webhook URL from Step 2
   * **Timeout**: `30` seconds
   * **Method**: POST

### Headers

The default `Content-Type: application/json` header is already added. No additional headers are needed for the automation platform webhook.

### Tool Parameters

3. Click **Add parameter** and configure:
   * **Name**: `customer_phone`
   * **Type**: `String`
   * **Description**: `The customer_phone variable from the call`

4. Click **Create** to save the tool

## Step 4: Test the Tool and Send Data to the Automation

After saving, we need to send test data so the automation can capture the webhook payload structure.

1. **Save** the tool
2. Go back to the **automation tab** and click **Load Data** to start listening
3. Go back to the **mid-call tool** and click **Test Tool**
4. Return to the automation tab — you should see the test data arrive with the `customer_phone` field in the body

Now add `/sync` to the end of the webhook URL in the mid-call tool's **Endpoint** field and **save**. With `/sync`, the tool will send the data and wait to receive the response back from the automation.

<Warning>
  The `/sync` at the end of the webhook URL is critical. Without it, the mid-call tool won't wait for the automation to finish and return data. With `/sync`, the tool waits for the automation response before continuing the conversation.
</Warning>

## Step 5: Add Split Text Step

Phone numbers from the mid-call tool come with a `+` prefix (e.g., `+1234567890`), but Google Sheets stores them without it. We need to strip the `+` before searching.

1. Click **+** to add a step after the webhook trigger
2. Search for **Text** and select **Split Text**
3. Configure:
   * **Text**: Select from Catch Webhook → Body → `customer_phone`
   * **Delimiter**: `+`

This splits the phone number by the `+` character. The second part (index 1) will contain the number without the prefix.

## Step 6: Add Google Sheets Lookup

Now we'll add the Google Sheets step that searches for the order by phone number.

1. Click **+** to add another step
2. Search for **Google Sheets** and select **Find Row**
3. Create or select a **Google Sheets connection**
4. Select your **spreadsheet** (e.g., "Orders AI") and **sheet name**
5. Configure the lookup:
   * **Column name**: `customer_phone`
   * **Search value**: Select the result from the Split Text step (index 1 — the number without `+`)
   * **Starting row**: `1`
   * **Number of rows**: `1`

<Tip>
  For testing, you can temporarily hardcode your own phone number (without the `+`) in the search value field. Once you see the row returned successfully, replace it with the dynamic value from the Split Text step.
</Tip>

## Step 7: Return the Data

The final step is to return the order data back to the mid-call tool so the AI can use it.

1. Click **+** to add another step
2. Search for **Return Response** (under Webhook actions)
3. Set the response body type to **JSON** and configure:

```json theme={null}
{
  "customer_name": "{{step_1[0]['values']['B']}}",
  "order_number": "{{step_1[0]['values']['C']}}",
  "order_status": "{{step_1[0]['values']['D']}}",
  "product": "{{step_1[0]['values']['E']}}"
}
```

4. **Map each field** by selecting the values from the Find Row step data (Find Row → Row 0 → Values)
5. **Test this step** to verify you receive the correct data

<Tip>
  You can return as many fields as you need. The AI will receive all this data and can use any of it during the conversation.
</Tip>

## Step 8: Publish the Automation

1. Verify all steps are correctly configured
2. Click **Publish** to make the flow live

## Step 9: Assign the Tool to Your Assistant

Now we need to connect the mid-call tool to your AI assistant so it can use it during calls.

1. Navigate to your AI assistant → **Prompts and Tools** tab
2. In the **Custom Tools** section, select `get_order_status` from the dropdown
3. **Save** the assistant

## Step 10: Configure the AI Prompt

Open the **AI Prompt Editor** to instruct the AI on when and how to use the tool. Click **Launch AI Prompt Editor** and describe what you need — for example, tell it to build a prompt that uses the `get_order_status` tool when a customer asks about their order.

The AI Prompt Editor will generate the appropriate system prompt rules. Review them, click **Accept**, then **Save**.

## Step 11: Test with a Real Call

1. Click **Speak to Assistant** to start a live voice test
2. When connected, ask about your order status
3. The assistant should call the `get_order_status` tool, look up your phone number in the Google Sheet, and tell you the order details

<Tip>
  If the lookup doesn't return data, check that the phone number in your Google Sheet matches the number without the `+` prefix. Also verify the Split Text step is correctly stripping the `+`.
</Tip>

## Best Practices

### Google Sheets Data

* **Store phone numbers without `+`** — Google Sheets doesn't support `+` as a number prefix, the automation handles stripping it
* **Avoid duplicate phone numbers** — the lookup returns the first match
* **Keep the sheet organized** — remove empty rows between data entries

### Tool Configuration

* **Set a reasonable timeout** (30 seconds) to account for automation processing time
* **Write a clear tool description** so the AI knows exactly when to use it
* **Include fallback instructions** in your prompt for when no data is found

### System Prompt Tips

* **Be specific** about what data fields the AI will receive
* **Provide examples** of how to use the data naturally in conversation
* **Handle edge cases** — empty fields, no match found, etc.

## Troubleshooting

### Common Issues

**Tool returns empty data:**

* Verify the phone number format matches between the Split Text output and Google Sheet
* Check Google Sheets connection authorization
* Test the automation manually with a known phone number

**Tool timeout:**

* Increase the timeout value in the mid-call tool settings
* Check that the automation is published and active
* Verify the `/sync` suffix is on the webhook URL

**AI doesn't use the tool:**

* Review the tool description — make it clear when to use it
* Check the system prompt has explicit instructions to use the tool
* Verify the tool is saved and associated with the correct assistant

**Automation not triggering:**

* Confirm the webhook URL is correct (including `/sync`)
* Check that the automation is published
* Review automation runs for error messages

**Phone number not matching:**

* Ensure the Split Text step is correctly stripping the `+` prefix
* Check that phone numbers in the Google Sheet are stored without `+`
* Verify the Split Text delimiter is set to `+`

## Next Steps

Once your order lookup is working:

* **Add more data columns** to your sheet (tracking number, shipping address, estimated delivery)
* **Combine with post-call automation** to update the sheet after each call
* **Create multiple lookup tools** for different data sources
* **Add a "write" tool** to let the AI update order notes during the call
* **Connect to a CRM or e-commerce platform** instead of Google Sheets for larger datasets


# Outbound Call on Form Submission
Source: https://docs.autocalls.ai/automation-platform/tutorials/outbound-form-call

Learn how to trigger AI calls when customers submit a form

# Outbound Call on Form Submission

This tutorial shows how to set up an automation flow that triggers an AI call when a customer submits a form on your website.

<iframe title="Tutorial: Outbound Call on Form Submission" />

## What You'll Learn

* Setting up a form submission trigger
* Configuring the Autocalls action
* Mapping form data to call variables
* Testing and deploying your flow


# Post-Call Email Automation
Source: https://docs.autocalls.ai/automation-platform/tutorials/post-call-email-automation

Learn how to automatically send personalized emails to customers after AI phone calls

This tutorial shows how to set up an automation that sends personalized follow-up emails to customers after AI phone calls, with conditional logic based on call outcomes and personalized content.

<iframe title="Tutorial: How to send an email after phone call ends" />

## What You'll Learn

* Setting up post-call email automation with conditional triggers
* Configuring email templates with dynamic content from calls
* Mapping call data and variables to email content
* Creating different email flows based on call success
* Best practices for professional follow-up communication

## Prerequisites

* Configured AI assistant with post-call variables and email collection
* Email service integration (Gmail)
* Understanding of post-call webhook automation
* Access to call testing functionality

## Step 1: Create Post-Call Email Automation

We'll create an automation that triggers after phone calls and sends personalized emails based on call outcomes.

<video />

1. **Navigate to Automation Platform**
2. **Create a new flow** from scratch
3. **Search for your calling platform** in triggers
4. **Select "Phone Call Ended"** trigger
   * This captures data from all completed calls to your selected assistant

## Step 2: Configure Assistant and Load Data

<video />

1. **Select your target assistant**
   * Each assistant supports only one post-call automation
   * All calls to this assistant will trigger this email flow
2. **Click "Load Data"** to set up the webhook and load sample call data
   * This automatically configures the webhook on your assistant
   * Sample data from your recent calls will be loaded for use in the next steps

## Step 3: Verify Assistant Variables

Before proceeding, make sure your assistant has the right variables configured:

1. **Check post-call variables** in your assistant's "Post-call Actions" tab:
   * **status**: Boolean indicating call success
   * **email**: Customer email address
   * Add any other variables you want to use in your email

<Frame>
  <img alt="Post-call variables for email content" />
</Frame>

2. **Check input variables** in your assistant's "Prompt & Tools" tab:
   * Ensure `email` variable is defined so the assistant collects it during calls

<Frame>
  <img alt="Call variables including email collection" />
</Frame>

### Adding New Post-Call Variables

If you add a new post-call variable after creating the automation:

1. **Define the new variable** in your assistant's "Post-call Actions" tab and save
2. **Return to your automation** and click **"Load Data"** again to refresh the available fields
3. **Re-evaluate an existing call** if needed to extract the new variable from past calls

## Step 4: Configure Conditional Email Logic

We only want to send emails when the call objective was achieved.

<video />

1. **Click the "+" sign** to add a step
2. **Search for "Branch"** in control flow
3. **Select Branch** to create conditional logic

<video />

4. **Configure the branch condition:**
   * **Select `status` variable** from call data
   * **Choose "Boolean is true"**
   * This creates two paths: True (qualified) and False (not qualified)

## Step 5: Set Up Email Service Integration

<video />

1. **On the True branch**, click "+"
2. **Search for your email service** (Gmail, Outlook, SMTP, etc.)
3. **Select "Send Email"** action

<video />

4. **Create email service connection:**
   * Authorize with your email provider
   * Configure SMTP settings if using custom email
   * Save the connection for future use

## Step 6: Configure Email Content and Recipients

<video />

1. **Configure recipient:**
   * Click on "To" email field
   * **Select customer email** from call variables
   * Ensure the email address is properly mapped

2. **Set email subject:**
   * Use dynamic content: "Thank you for your time, `{customer_name}`!"
   * Include company name or call reference
   * Keep subject professional and relevant

<video />

1. **Compose email body with dynamic content:**
   * **Click on the "Body" field** to start writing your email
   * **Type your email content** with placeholders for variables
   * **Example email template:**

```
Hi {customer_name},

Thank you for taking the time to speak with us today. Here's a transcript of our conversation:

{formatted_transcript}

Next Steps:
- We'll follow up as discussed
- Feel free to reach out with any questions
- [Include specific next steps based on your business]

Best regards,
[Your Name/Company]
[Contact Information]
```

2. **Add dynamic variables to your email:**
   * **To replace `{customer_name}`**:
     * **Click where you want the variable** in your email text
     * **A popup will appear** with available variables
     * **Search for and select "customer\_name"** from call variables
     * **Click "Insert"** to add the variable
   * **To replace `{formatted_transcript}`**:
     * **Click where you want the transcript** in your email text
     * **Navigate to "Post Call Variables"** in the popup
     * **Select the "formatted\_transcript" variable**
     * **Click "Insert"** to add the variable

## Step 7: Advanced Email Templates

You can create more professional emails by using HTML formatting:

1. **Select "HTML" as body type** in your email action
2. **In the body field, add HTML code** for enhanced formatting
3. **Use dynamic variables** the same way as in plain text emails

## Step 8: Test Email Automation

<video />

1. **Click "Test Step"** to send test email
2. **Verify successful delivery** in test results
3. **Check your email inbox:**
   * Verify email was received
   * Check that dynamic content populated correctly
   * Review formatting and professionalism

## Step 9: Publish and Monitor

<Frame>
  <img alt="Publishing email automation" />
</Frame>

1. **Click "Publish"** to activate your email automation
2. **Monitor automation runs** for successful email delivery

## Best Practices

### Email Content

* **Professional tone** appropriate for your industry
* **Clear subject lines** that indicate purpose
* **Personalized content** using call data effectively
* **Clear call-to-action** for next steps

## Troubleshooting

### Common Issues

**Emails not sending:**

* Verify email service connection and authorization
* Check that customer email addresses are valid
* Confirm email action is on correct conditional branch
* Verify automation is published and active

**Dynamic content not populating:**

* Check variable mapping in email template
* Verify post-call variables are being extracted correctly
* Ensure call variables contain email data
* Test with various call scenarios

Your customers will now receive professional, personalized follow-up emails after every successful call, improving relationship building and conversion rates!


# Post-Call SMS Automation
Source: https://docs.autocalls.ai/automation-platform/tutorials/post-call-sms-automation

Learn how to automatically send SMS messages to customers after AI phone calls end

This tutorial shows how to set up an automation that automatically sends SMS messages to customers after AI phone calls end, with conditional logic based on call outcomes.

<iframe title="Tutorial: How to send an SMS after AI phone call ends" />

## What You'll Learn

* Setting up post-call webhook automation triggers
* Configuring conditional logic based on call success
* Mapping call data to SMS content
* Testing post-call automations with live calls
* Best practices for SMS follow-up messaging

## Prerequisites

* Configured AI assistant with post-call variables
* SMS-enabled phone number in your platform
* Basic understanding of automation flows
* Access to call testing functionality

## Step 1: Create Post-Call Automation Flow

We'll start by creating an automation that triggers when a phone call ends.

<video />

1. **Navigate to Automation Platform**
2. **Create a new flow** from scratch
3. **Search for your calling platform** in the trigger section
4. **Select "Phone Call Ended"** trigger
   * This trigger activates when any call to your selected assistant completes

## Step 2: Configure Assistant and Load Data

<video />

1. **Select the assistant** you want to automate
   * Each assistant can only have one "phone call ended" automation
   * All calls to this assistant will go through this automation
2. **Click "Load Data"** to set up the webhook and load sample call data
   * This automatically configures the webhook on your assistant
   * Sample data from your recent calls will be loaded for use in the next steps

## Step 3: Verify Assistant Variables

Before proceeding, make sure your assistant has the right variables configured:

1. **Check post-call variables** in your assistant's [Post-call Actions](/ai-assistants/settings/post-call-actions) tab:
   * **status**: Boolean (true/false) indicating if call objective was achieved
   * **summary**: Text summary of the call conversation
   * These variables are extracted by AI after each call
   * You can add more variables to use in your SMS content (e.g., `customer_name`, `appointment_date`)

<Frame>
  <img alt="Post-call variables configuration" />
</Frame>

### Adding New Post-Call Variables

If you add a new post-call variable after creating the automation:

1. **Define the new variable** in your assistant's "Post-call Actions" tab and save
2. **Return to your automation** and click **"Load Data"** again to refresh the available fields
3. **Re-evaluate an existing call** if needed to extract the new variable from past calls

## Step 4: Add Conditional Logic for Goal-Based SMS

We want to send SMS only when the call objective is achieved, so we need a decision branch in our automation.

<video />

1. **Click the "+" sign** to add a new step
2. **Search for "Branch"** in the control flow options
3. **Select the Branch** component

<video />

4. **Configure the branch condition:**
   * **A sidebar will appear** for setting up the condition
   * **Search for the `status` variable** from your call data
   * **Select the `status` variable**
   * **Choose "Boolean is true"** as the condition type
   * This creates **two paths**: **True (left)** and **False (right)**

<Note>
  The `status` variable is Boolean (true/false). After each call, this variable will be extracted and will be `true` if the call objective was achieved, otherwise `false`. The branch will execute the "True" path when the goal was achieved and the "False" path when it wasn't.
</Note>

**Understanding the Logic:**

* **True path (left)**: Actions for successful calls (objective achieved)
* **False path (right)**: Actions for unsuccessful calls (objective not achieved)

## Step 5: Configure SMS Action for Successful Calls

Now we'll add the SMS action that triggers when the call objective is achieved.

<video />

1. **On the "True" branch** (successful calls), **click the "+" sign**
2. **Search for your calling platform**
3. **Select "Send SMS to Customer"**

<video />

4. **Select an SMS-enabled phone number** from your platform:
   * **Choose an existing number** that you have in your platform
   * This number will be the **sender of your SMS messages**
   * Make sure the number has SMS capabilities enabled

## Step 6: Map SMS Content and Recipient

Now we'll configure who receives the SMS and what message they get.

<video />

1. **Configure the SMS recipient:**
   * **Click on "Customer Phone" input field**
   * **A sidebar will open** showing available data from the call
   * **Search for the variable that holds the phone number**
   * **Select the phone number** from your call data
   * **Click "Insert"** to map the field

<video />

2. **Configure the SMS message content:**
   * **Move to the text message field**
   * **Use the `summary` variable** for personalized content
   * The `summary` is the post-call variable that contains AI-generated call summary
   * **You can write custom text** + dynamic summary
   * **Example**: "Thank you for your time! Here's a summary of our call: "

<Note>
  The `summary` variable is filled automatically after each call based on the conversation discussion and will be unique for each customer interaction.
</Note>

<video />

3. **Test the SMS action:**
   * **Click "Test Step"** to send a test SMS using your call data
   * **Verify successful delivery** in the test results
   * **Check your phone** for the actual SMS message
   * **Confirm the message content** includes the call summary

## Step 7: US Phone Numbers - Twilio Integration

<Note>
  **Important for US phone numbers**: If your SMS messages need to be sent to US phone numbers, you will need to use Twilio instead of our AI calling platform's SMS feature. This requires A2P verification for compliance with US regulations.
</Note>

### Setting Up Twilio for US SMS

If you need to send SMS to US numbers, follow these steps:

1. **Purchase a phone number from Twilio** with SMS capabilities
2. **Complete [A2P 10DLC registration](https://www.twilio.com/docs/messaging/guides/10dlc)** in your Twilio account
3. **Replace the SMS action** in your automation:

<video />

* **Search for "Twilio"** in the action search
* **Select "Send SMS"** from Twilio options

<video />

* **Create new connection** when prompted
* **Complete Account SID and Auth Token** from your Twilio dashboard
* **Save the connection**

4. **Configure Twilio SMS:**
   * **Select your Twilio phone number**
   * **Map customer phone number** (same process as above)
   * **Configure message body** (same process as with our platform)
   * **Test the step** to verify delivery

<Warning>
  US SMS regulations require [A2P 10DLC registration](https://www.twilio.com/docs/messaging/guides/10dlc) for business messaging. Using unverified numbers may result in message blocking or account suspension.
</Warning>

## Step 8: Publish and Activate Automation

<Frame>
  <img alt="Publishing the automation" />
</Frame>

1. **Click "Publish"** to activate your automation
2. **Your post-call SMS automation is now live and ready**

**What happens now:**

* **After each call** with the selected assistant
* **If the objective was achieved** (`status` = true)
* **The customer will automatically receive an SMS** with the call summary

3. **Monitor automation performance:**
   * **Click "Runs"** to see execution history
   * **Verify SMS delivery** for successful calls
   * **Monitor any failed executions**
   * **Track which calls triggered SMS** vs which didn't

<Tip>
  From now on, after each call with the objective achieved, the customer will receive an SMS automatically. This improves follow-up consistency and customer engagement.
</Tip>

### SMS Delivery Tracking

Monitor your SMS automation effectiveness:

* **Delivery rates**: Track successful SMS delivery
* **Response rates**: Monitor customer engagement
* **Opt-out handling**: Respect customer preferences

## Best Practices

### Message Content

* **Keep messages concise** and valuable
* **Personalize with call data** when relevant
* **Include clear next steps** or contact information

### Timing Considerations

* **Send immediately** after successful calls for best engagement
* **Consider time zones** for your customer base
* **Avoid late-night messaging** unless appropriate for your business

## Troubleshooting

### Common Issues

**SMS not sending:**

* Verify phone number has SMS capabilities
* Check customer phone number format (+1234567890)
* Confirm SMS action is on the correct branch

**Automation not triggering:**

* Ensure webhook is enabled in assistant settings
* Verify automation is published and active
* Check that calls are completing successfully

**Wrong message content:**

* Verify variable mapping in SMS content
* Check that post-call variables are being extracted
* Test with various call scenarios

## Next Steps

Once your basic SMS automation is working:

* **Add email automation** for additional follow-up
* **Create different messages** for different call outcomes
* **Integrate with CRM systems** to log communication
* **Set up advanced analytics** to track engagement
* **A/B test different message templates** for optimal results

Your customers will now receive personalized SMS messages after successful calls, improving engagement and follow-up consistency!


# Version History
Source: https://docs.autocalls.ai/automation-platform/versioning

Learn how flow versioning works in Autocalls.ai

Autocalls.ai keeps track of all published flows and their versions. Here’s how it works:

1. You can edit a flow as many times as you want in **draft** mode.
2. Once you're done with your changes, you can publish it.
3. The published flow will be **immutable** and cannot be edited.
4. If you try to edit a published flow, Autocalls.ai will create a new **draft** if there is none and copy the **published** version to the new version.

This means you can always go back to a previous version and edit the flow in draft mode without affecting the published version.

<img alt="Flow History" />

As you can see in the following screenshot, the yellow dot refers to DRAFT and the green dot refers to PUBLISHED.


# Overview of No-Code Automation
Source: https://docs.autocalls.ai/automation/overview

Learn about Autocalls.ai's built-in automation engine for creating workflows without coding

<Card title="Read the full documentation" icon="book-open" href="/automation-platform/introduction">
  This is a brief overview of our automation capabilities. For in-depth
  documentation, tutorials, and advanced features, visit our dedicated
  [Automation Platform Documentation](/automation-platform/introduction).
</Card>

Autocalls.ai includes an internal automation engine (similar to Zapier or Make) that lets you build flows—no coding required. For instance:

1. **Trigger**: A call ends.
2. **Action**: A Slack notification is sent with call outcome and transcript.

## Key Concepts

* **Triggers**: Events inside Autocalls.ai (e.g., "call ended," "inbound call context injection").
* **Actions**: Steps that happen in response (e.g., "send email," "update Google Sheets," "webhook to CRM").

## Common Use Cases

* **Post-Call Data Handling**: Log transcripts in a database or notify your team of new leads.
* **Lead Import**: Automatically fetch new leads from a Google Sheet or CRM into an outbound campaign.
* **Appointment Scheduling**: Once a caller confirms a time with the AI, you create or update a calendar event.

## Setting Up a Workflow

1. Go to **Automations** in your dashboard.
2. Click **Create Workflow**.
3. Pick a **trigger** (like "Call Ended") and select the **assistant**.
4. Add **actions** (like "Send Email to Team," "Add Row in Sheets," etc.).
5. Test and monitor logs to ensure everything runs smoothly.

***

**Tip:** Keep your workflows simple at first. Complex logic is possible, but it's best to start with a single trigger → single action until you get comfortable.

**Want to learn more?** Check out our [detailed automation documentation](/automation-platform/introduction) for advanced features, tutorials, and best practices.


# Webhook & API
Source: https://docs.autocalls.ai/automation/webhook-api

Learn how to use webhooks and the REST API for custom integrations and automation

If you want deeper customization beyond no-code blocks, Autocalls.ai supports **webhooks** and a **REST API**.

## 1. Webhooks

* **When to Use**: Trigger events in external systems the moment something happens in Autocalls.ai (e.g., "Call Ended,").
* **Configuration**: Set a webhook URL in your assistant/campaign settings or the automation platform.
* **Payload**: Typically includes call ID, transcript, call outcome, or any user data collected.

## 2. REST API

* **Key Functions**:

  1. **Create/Update Leads**
  2. **Manage Campaigns**

* **Auth & Rate Limits**: Usually uses API tokens. Check [API docs](/api-reference/introduction) for details on endpoints and usage quotas.

## 3. Example Use Cases

* **Real-Time CRM Sync**: For each new call, post data to your CRM's endpoint.
* **Custom Dashboards**: Pull call data into your own analytics dashboard.

***

**Note:** You'll find the official API reference in a dedicated docs section or via your Autocalls.ai dashboard. Always secure your tokens and test endpoints in a dev environment.


# Creating a Campaign
Source: https://docs.autocalls.ai/campaigns/creating-campaigns

Step-by-step guide to setting up call, WhatsApp, or SMS campaigns

Create and configure a campaign to reach many leads on phone, WhatsApp, or SMS.

## Prerequisites

Depends on the channel:

* **Call:** OUTBOUND assistant with a phone number, minutes balance
* **WhatsApp:** Connected sender + approved template, chat credits
* **SMS:** SMS-capable from-number (SMS campaigns may be temporarily unavailable)
* **Leads ready** to import or add manually

## Campaign Setup

### 1. Basic Information

**Campaign Name:** Descriptive name for easy identification\
**Channel:** `Call`, `WhatsApp`, or `SMS`\
**Call only — Assistant:** Which OUTBOUND AI assistant will dial

<Note>
  For call campaigns, the assistant's voice, prompt, and tools are used on every dial. WhatsApp campaigns send templates; they do not need an outbound assistant.
</Note>

### 2. Scheduling Configuration

#### Schedule windows

Prefer **one or more daily windows** (`start` / `end` as HH:MM):

* Multiple intervals allowed (e.g. 09:00–12:00 and 14:00–18:00)
* Overnight windows when end is earlier than start (e.g. 16:00→02:00)
* Optional **scheduled start** datetime to auto-start later

Legacy single start/end times still work and map to one window.

#### Allowed Days

Select which days of the week to send/call:

* **Default:** Monday through Sunday
* **Business only:** Monday through Friday
* **Custom:** Choose specific days

<Tip>
  **Recommendation:** For business outreach, use Monday–Friday daytime windows in the prospect's timezone.
</Tip>

### 3. Retry Settings

#### Basic Retry Options

* **Max retries:** 1-5 attempts for unanswered calls (default: 3)
* **Retry interval:** 10-4320 minutes between attempts (default: 60 minutes)

#### Advanced Retry Conditions

**Retry on Voicemail:**

* **Enabled:** Continue calling until human answers
* **Disabled:** Count voicemail as attempted contact

**Retry Until Goal Completed:**

* **Enabled:** Keep calling until objective is achieved
* **Goal variable:** Select boolean variable from assistant's post-call schema
* **Use case:** Sales calls, appointment booking, lead qualification

<Warning>
  **Goal-based retry** requires your assistant to have post-call variables configured with boolean fields (true/false).
</Warning>

### 4. Lead Management

#### Adding Leads

**Manual Entry:**

* Add individual leads with phone numbers
* Include names and additional contact information

**CSV Import:**

* Upload spreadsheet with lead information
* Required: Phone number column
* Optional: Name, email, additional fields

**Integration Import:**

* Import from GoHighLevel, Google Sheets, or other connected platforms
* Automatic sync with external lead sources

#### Secondary Contacts

Call campaigns only — additional phone numbers for the same lead:

* **Use case:** Multiple decision-makers, backup contacts
* **Logic:** Campaign tries secondary numbers if the primary does not connect
* **Not available** on WhatsApp/SMS campaigns

### 5. WhatsApp / SMS (text channels)

**WhatsApp**

* Select sender + approved template
* Map template placeholders to lead variables
* Set **messages per minute** (1–10). Across all your active WhatsApp campaigns, at most **10** sends are in flight at once.

**SMS**

* Select SMS-capable from-number and message body (`{{variable}}` placeholders)
* Rate via messages per minute

**Call → text fallback (call campaigns)**

* After a lead hits max call retries, optionally send a WhatsApp template or SMS once
* Missing chat credits skip that fallback send; the call campaign keeps dialing other leads

## Starting Your Campaign

### Pre-launch Checklist

* [ ] Channel config complete (assistant / WhatsApp template / SMS number)
* [ ] Sufficient balance (minutes and/or chat credits)
* [ ] Leads added with valid phone numbers
* [ ] Schedule windows and days set
* [ ] Retry (and optional fallback) match your goals

### Launch Process

1. **Review settings** one final time
2. **Click "Start Campaign"** to begin
3. **Monitor progress** in campaign dashboard
4. **Adjust settings** if needed (pause campaign first)

## Campaign Monitoring

### Real-time Status

* **Calls in progress:** Currently active calls
* **Calls completed:** Finished calls with outcomes
* **Leads remaining:** Contacts still to be called
* **Next call time:** When next call will be made

### Monitoring Progress

Track lead status and call results in the campaign dashboard. See [Campaign Overview](/campaigns/index#campaign-monitoring) for detailed status explanations.

## Managing Active Campaigns

### Pausing a Campaign

* **Immediate stop:** Current call completes, no new calls start
* **Resume capability:** Can restart without losing progress
* **Use cases:** Adjust settings, review results, temporary pause

### Modifying Settings

1. **Pause the campaign** first
2. **Edit configuration** as needed
3. **Save changes**
4. **Resume campaign** to continue with new settings

### Adding More Leads

* **Add to active campaign:** New leads join existing retry queue
* **Import additional contacts:** CSV or integration import
* **Secondary contacts:** Add backup numbers for existing leads

## Best Practices

* **Conservative scheduling:** Business hours, respect time zones
* **Start with 2-3 retries:** Monitor and adjust based on feedback
* **Clean lead data:** Valid numbers, remove duplicates
* **Compliance:** Follow local regulations and opt-out requests

<Note>
  For troubleshooting common issues, see [Campaign Troubleshooting](/troubleshooting/campaigns).
</Note>


# Campaigns Overview
Source: https://docs.autocalls.ai/campaigns/index

Create and manage call, WhatsApp, and SMS campaigns to reach leads at scale

Campaigns automate outreach to many leads on one channel: **phone calls**, **WhatsApp templates**, or **SMS** (when enabled). Configure schedule windows, retries, and lead lists once, then start the campaign.

## What is a Campaign?

A campaign contacts a list of leads using your chosen channel. Call campaigns use an OUTBOUND AI assistant; WhatsApp campaigns use an approved template; SMS campaigns use an SMS-capable from-number and message body.

<CardGroup>
  <Card title="Channels" icon="layer-group">
    **Call, WhatsApp, or SMS**

    Same lead list workflow — pick the channel when you create the campaign
  </Card>

  <Card title="Lead Management" icon="users">
    **Import or add leads**

    CSV, integrations, API, or manual entry. Secondary contacts are for call campaigns only.
  </Card>

  <Card title="Schedule windows" icon="calendar">
    **One or more daily intervals**

    Overnight windows (e.g. 16:00→02:00) and optional scheduled auto-start
  </Card>

  <Card title="Retries & fallback" icon="repeat">
    **Retries per lead**

    Call campaigns can also send a WhatsApp/SMS follow-up after max retries
  </Card>
</CardGroup>

## Campaign Status

<AccordionGroup>
  <Accordion title="Draft" icon="file">
    Campaign is being configured but not yet active. Add leads and configure settings.
  </Accordion>

  <Accordion title="In Progress" icon="play">
    Campaign is actively making calls according to your schedule and retry settings.
  </Accordion>

  <Accordion title="Paused" icon="pause">
    Campaign is temporarily stopped. Can be resumed without losing progress.
  </Accordion>

  <Accordion title="Completed" icon="check">
    All leads have been successfully contacted or marked complete.
  </Accordion>
</AccordionGroup>

## Key Features

### Scheduling & Timing

* **Schedule windows:** One or more daily `{start, end}` intervals (preferred over a single start/end pair)
* **Overnight windows:** End earlier than start (e.g. 16:00→02:00) is supported
* **Allowed days + timezone:** Campaign timezone controls when the window applies
* **Scheduled start:** Optionally auto-start at a future datetime

### Call campaigns

* OUTBOUND assistant + from-numbers
* **Max parallel calls** (plan-bounded)
* **Retry on voicemail** / **retry until goal** (boolean [post-call variables](/ai-assistants/settings/post-call-actions#post-call-variables))
* Optional **WhatsApp/SMS fallback** after max call retries (low chat credits skip the fallback — they do not pause the voice campaign)

### WhatsApp campaigns

* Sender + approved template + variable mapping
* **`messages_per_minute`** (1–10) per campaign
* **User-wide pool of 10** in-flight WhatsApp sends across all your active WhatsApp campaigns

### SMS campaigns

* SMS-capable from-number + body (`{{variable}}` placeholders)
* May be temporarily unavailable on the platform — start will fail with a clear message if disabled

### Lead Types

* **Primary leads:** Main contacts imported or added to campaign
* **Secondary contacts:** Call campaigns only — extra numbers to try
* **Lead status tracking:** Monitor progress and outcomes

## Requirements

Before starting a campaign:

<Warning>
  **Call campaigns:** Your assistant must have a [phone number configured](/ai-assistants/settings/general#phone-number-configuration) for outbound calls.
</Warning>

* **Channel config ready** — assistant (call), WhatsApp sender+template, or SMS number+body
* **Sufficient balance** — minutes for calls; chat credits for WhatsApp
* **Leads added** with valid phone numbers (E.164 recommended)

## Quick Start

1. **Create Campaign:** Choose channel (call / WhatsApp / SMS) and required config
2. **Set Schedule:** Define schedule windows and allowed days
3. **Configure Retries:** Set retry attempts and intervals
4. **Add Leads:** Import from CSV or add manually
5. **Start Campaign:** Start when ready — sending/dialing begins on the next scheduler cycle

<Note>
  For detailed setup instructions, see [Creating a Campaign](/campaigns/creating-campaigns).
</Note>

## Campaign Monitoring

### Lead Status Tracking

Monitor individual lead progress through the campaign:

* **Created:** Ready to be called
* **Scheduled:** Queued for next call attempt
* **Processing:** Currently being called
* **Completed:** Successfully contacted or goal achieved
* **Rescheduled:** Scheduled for retry attempt
* **Max Retries:** Reached maximum retry attempts

**Manual lead management:** You can change lead status in the leads table:

* **Set to "Created":** Reset lead to be called again
* **Set to "Completed":** Mark lead as finished to stop calling

### Call Results

Individual call outcomes with detailed status:

* **Initiated:** Call started
* **Ringing:** Phone is ringing
* **In Progress:** Call connected and active
* **Completed:** Call finished successfully
* **Busy:** Line was busy
* **Unanswered:** No one answered
* **Failed:** Technical issue prevented call

## Troubleshooting

**Campaign won't start:**

* Check if assistant has phone number configured
* Verify sufficient account balance
* Ensure leads are added to campaign

**No calls being made:**

* Wait 10-15 minutes after starting - campaigns take time to initialize
* Check if current time is within allowed calling hours
* Verify allowed days include current day
* Confirm leads have valid phone numbers

**Too many/few retries:**

* Adjust max retries setting (1-5 attempts)
* Modify retry interval (10-4320 minutes)
* Review retry conditions (voicemail, goal completion)

<Tip>
  **Best Practice:** Start with conservative retry settings and adjust based on campaign performance and customer feedback.
</Tip>

<Note>
  For detailed troubleshooting guidance, see [Campaign Troubleshooting](/troubleshooting/campaigns).
</Note>


# Handling Interruptions & Speech Sensitivity
Source: https://docs.autocalls.ai/conversation-design/interruptions

Configure how your AI assistant handles interruptions, voice activity detection, and speech patterns

Phone conversations can be messy—callers may interrupt the AI or have background noise. Autocalls.ai provides **voice activity detection** and **speech settings** to handle these situations.

## 1. Voice Activity Detection (VAD)

* **What It Is**: A setting that helps the AI wait for the user to finish talking before responding.
* **Configuration**: In the assistant's advanced settings, you can enable or disable VAD.
  * *High Sensitivity*: AI might interrupt less, but could lead to awkward pauses.
  * *Low Sensitivity*: AI might talk over the user if they pause mid-sentence.

## 2. Speech Speed & Filler Usage

* **Speech Speed**: Some voices allow you to slow down or speed up how quickly the AI talks.
* **Filler Usage**: Decide if the AI uses "umm," "uhh," or short "mhm" acknowledgments to sound more natural.

## 3. Interruptions

* If a user starts speaking while the AI is talking, the AI can attempt to stop and listen. However, perfect interruption handling can't be guaranteed due to phone audio overlap.
* Encourage shorter AI responses in your prompt to reduce collision with the caller's speech.

***

**Tip:** Conduct test calls to find the right balance of sensitivity and speed. Overly fast responses or overly long monologues can frustrate callers.


# Knowledge Bases
Source: https://docs.autocalls.ai/conversation-design/knowledge-bases

Learn how to provide your AI assistant with access to FAQs, documents, and other knowledge sources

Knowledge bases enable your AI assistant to access and reference custom information from various sources like websites, documents, and files. This powerful feature allows your assistant to provide accurate, context-specific responses based on your own content.

## Approaches for Knowledge Integration

### 1. Copy-Paste into Prompt

* **Pros**: Quick to set up, immediate availability.
* **Cons**: Large texts can slow down responses or risk partial "hallucination."
* **Usage**: Useful for short references, like top 10 FAQs.

### 2. Knowledge Base Feature

Our dedicated Knowledge Base feature allows you to store and manage documents that the AI can query on demand:

<CardGroup>
  <Card title="Website Content" icon="globe">
    **Scrape entire websites** to capture all available information

    * Company websites
    * Product documentation
    * FAQ pages
    * Blog content
  </Card>

  <Card title="Document Files" icon="file">
    **Upload various file formats** with your information

    * **PDF files:** Manuals, guides, reports
    * **Word documents (.docx):** Policies, procedures
    * **Text files (.txt):** Simple content, notes
  </Card>
</CardGroup>

#### Processing Status

Every knowledge base goes through different processing stages:

<AccordionGroup>
  <Accordion title="Empty" icon="folder-open">
    No documents added yet. Add content to activate the knowledge base.
  </Accordion>

  <Accordion title="Processing" icon="clock">
    Documents are being analyzed and indexed. Processing time varies by content size.
  </Accordion>

  <Accordion title="Active" icon="check">
    Knowledge base is ready. Your AI assistant can now search and reference this information.
  </Accordion>

  <Accordion title="Failed" icon="x">
    Processing failed. Common causes: protected websites, inaccessible content, corrupted files.
  </Accordion>
</AccordionGroup>

#### Integration Modes

Choose how your AI assistant accesses knowledge base information:

<CardGroup>
  <Card title="Function Call" icon="function">
    **Recommended:** Searches only when needed. More efficient and faster.

    **Best for:** General conversations
  </Card>

  <Card title="Prompt Injection" icon="syringe">
    **Comprehensive:** Searches after every customer message. More accurate but slower.

    **Best for:** Support-focused assistants. Use with [filler audio](/ai-assistants/filler-audio)
  </Card>
</CardGroup>

## Best Practices

* Keep info concise, use bullet points.
* Separate topics with clear headings so the AI can parse more effectively.
* Monitor call transcripts to confirm the AI references your data correctly.
* Use publicly accessible URLs for website scraping
* Consider file size and processing time for large documents

## Website Scraping Considerations

<Warning>
  **Website Protection:** Some websites have anti-scraping protection that can cause processing to fail. If you own the website, temporarily disable protection during scraping.
</Warning>

**Common issues:**

* Cloudflare protection, rate limiting, login requirements
* JavaScript-heavy sites, protected content

**Solutions:**

* Use publicly accessible URLs
* Export content manually and upload as documents
* Contact support for protected content assistance

## Setup Process

1. Navigate to Knowledge Bases in your dashboard
2. Click "Create Knowledge Base"
3. Add name and description
4. Upload documents (PDF, DOCX, TXT) or add website URLs
5. Wait for processing to complete
6. Assign to your assistant in [Assistant Settings](/ai-assistants/settings/prompt-and-tools#knowledge-base)

## Usage

Once connected, your assistant automatically searches the knowledge base during conversations to provide accurate, informed responses based on your content.

**Search functionality:** The AI searches through all documents in your knowledge base to find relevant information based on the customer's question and provides context-aware responses.

## Troubleshooting

**Processing fails:** Check if URLs are publicly accessible, disable website protection if you own it
**No search results:** Verify content relevance, ensure processing is complete (Active status)
**Slow responses:** Switch from Prompt Injection to Function Call mode

***

**Note:** For detailed configuration and advanced settings, see the [Assistant Settings Guide](/ai-assistants/settings/prompt-and-tools#knowledge-base).


# Language & Accent Support
Source: https://docs.autocalls.ai/conversation-design/language-support

Explore available languages and accents for your AI assistant, and learn how to request new ones

Autocalls.ai offers multiple languages and accents for your AI assistant. Choose from built-in sets or request new ones if needed.

## 1. Available Languages

* English (various accents: US, UK, Australian, etc.)
* Spanish (Latin American, Spain accent)
* French, German, Italian
* **Others**: +40 languages supported, [play samples here](https://autocalls.ai/#languages-available)

## 2. Requesting a New Language

* If your language is missing, contact support. We may add it if feasible. Some might require a one-time fee for model training or verification.

## 3. Accent Tuning

* Within a language, you can pick certain accents (like US English vs. British English).
* Speed and pitch settings can further localize the sound.

## 4. Testing & Verification

* Always run sample calls in your chosen language to ensure recognition is solid.
* AI recognition quality can vary; watch transcripts for repeated errors and refine your prompt or speech speed.

***

**Note:** Additional fees or wait times might apply for lesser-known languages or custom accent requests.


# Prompt Writing Basics
Source: https://docs.autocalls.ai/conversation-design/prompt-basics

Learn how to write effective system prompts and initial messages for your AI assistants

Autocalls.ai uses a **System Prompt** to guide how your AI assistant interacts with callers. Crafting an effective prompt is key to smoother, more accurate phone conversations.

## 1. System Prompt vs. Initial Message

* **System Prompt**: Overall instructions and context. Example:\
  *"You are the Support Bot for TechMasters Inc. Greet politely, ask for a name, handle basic troubleshooting, and transfer the call if the issue is complex."*

* **Initial Message**: The first thing the AI says, especially for inbound. Example:\
  *"Thank you for calling TechMasters! How can I assist you today?"*

## 2. Clarity & Structure

* **Be Specific**: Outline the main purpose, tone, and steps you want the AI to follow.
* **Use Examples**: Show sample dialogues. *"If the user says they have a billing question, ask them for their invoice number."*

## 3. Handling "Unknown" Cases

* If a user asks about something off-topic, decide whether the AI should:
  * Provide a default response: *"I'm not sure, let me transfer you…"*
  * Gather more details.

## 4. Keep It Short & Focused

* A short prompt often works best; too-long instructions can make the AI slower or prone to "hallucination."
* If you have lengthy content, consider a knowledge-base or chunk your text with headings.

***

**Tip:** Periodically review your transcripts to see where the AI might need more or fewer instructions.


# Conversations Overview
Source: https://docs.autocalls.ai/conversations/overview

Track and review text-based conversations with your AI assistant

Conversations provide a record of all text-based interactions with your AI assistants through web widgets, WhatsApp, and test interfaces.

## What Are Conversations?

Conversations are text-based chat sessions between users and your AI assistants through web widgets, WhatsApp Business, and test interfaces.

## Conversation Sources

Conversations are created through:

### Web Widget Interactions

When website visitors use your embedded web widget in chat or voice & chat mode, each session creates a conversation record.

**Includes:**

* All messages exchanged
* Variables collected from pre-chat forms
* Variables extracted during conversation
* Total cost and token usage
* Session timestamps

### WhatsApp Conversations

When customers message your WhatsApp Business number, each conversation thread creates a conversation record.

**Includes:**

* Complete message history
* Customer phone number
* AI assistant responses
* Cost and usage metrics
* 24-hour messaging window status

<Info>
  WhatsApp conversations follow Meta's 24-hour messaging window rules. Within this window, your AI can send free-form replies. After 24 hours, you must use approved template messages to re-engage. Learn more in our [WhatsApp documentation](/whatsapp/overview).
</Info>

### Test Chat Sessions

When you test your assistant using the Test Chat interface, each test session creates a conversation record marked as "Test."

**Useful for:**

* Reviewing test sessions
* Debugging conversation flow
* Analyzing assistant responses
* Validating variable collection

## Conversation Types

| Type           | Badge Color | Source                     |
| -------------- | ----------- | -------------------------- |
| **Test**       | Orange      | Test Chat interface        |
| **Web Widget** | Purple      | Website embedded widget    |
| **WhatsApp**   | Green       | WhatsApp Business messages |

**Test Conversations**

* Created from Test Chat interface
* Marked with orange "Test" badge
* Used for development and testing

**Web Widget Conversations**

* Created from website widget
* Marked with purple "Web widget" badge
* Real customer interactions

**WhatsApp Conversations**

* Created from WhatsApp Business messages
* Marked with green "WhatsApp" badge
* Customer interactions via WhatsApp

## Why Track Conversations?

* Review customer interactions and improve assistant responses
* Monitor assistant performance and conversation quality
* Track costs, token usage, and engagement metrics
* Debug conversation flow and validate variable collection

## Conversation Data

Each conversation includes:

* Message history with timestamps
* Variables collected (from pre-chat forms or extracted by AI)
* Cost and token usage metrics
* Conversation type (Test, Web Widget, or WhatsApp)
* Customer identifier (phone number for WhatsApp)

## Accessing Conversations

Navigate to the **Conversations (chat)** page from your dashboard to view all conversation records.

The navigation badge shows your total conversation count, helping you track activity at a glance.

<Note>
  Conversations are tracked separately from phone calls. Phone calls are tracked in the **Calls** page, while conversations (text-based chat) are tracked here.
</Note>

## Next Steps

* Learn how to [view and manage conversations](/conversations/viewing-and-managing)
* Set up a [web widget](/ai-assistants/web-widget) to start collecting conversations
* Connect [WhatsApp Business](/whatsapp/overview) for messaging conversations
* Use [test chat](/ai-assistants/test-chat) to create test conversations


# Viewing & Managing Conversations
Source: https://docs.autocalls.ai/conversations/viewing-and-managing

How to view, filter, and manage your conversation history

Access and manage all your text-based conversations with your AI assistants.

## Accessing Conversations

1. Navigate to **Conversations (chat)** in your sidebar
2. View the list of all conversations
3. The badge shows your total conversation count

<Note>
  If you don't have any conversations yet, you'll see an empty state. Conversations will appear once customers interact with your [web widget](/ai-assistants/web-widget), [WhatsApp Business](/whatsapp/overview), or when you use [test chat](/ai-assistants/test-chat).
</Note>

<Frame>
  <img alt="Conversations List View" />
</Frame>

## Conversations Table

The conversations table displays:

**Type:** Badge showing "Test", "Web widget", or "WhatsApp"

**Last Messages:** Preview of recent messages in the conversation

**Variables:** Variables collected during the conversation

**Message Count:** Number of messages exchanged

**Cost:** Total cost of the conversation

**Assistant:** Which assistant handled the conversation

**Started:** When the conversation started

**Last Activity:** Last message timestamp

## Filtering Conversations

Use filters to find specific conversations:

### By Type

Filter by conversation source:

* **Test:** Only test chat sessions
* **Web widget:** Only website widget conversations
* **WhatsApp:** Only WhatsApp Business conversations

### By Assistant

Select specific assistant to view only their conversations.

### By Date Range

Use the date range picker to filter conversations by creation date:

* Last 7 days
* Last 30 days
* Last 90 days
* Custom date range

## Viewing Conversation Details

Click on any conversation to view complete details:

<Frame>
  <img alt="Conversation Detail View" />
</Frame>

### Info Section

View conversation details and metrics:

* **Type:** Badge showing source (Test, Web widget, or WhatsApp)
* **Assistant:** Which assistant handled the conversation
* **Customer Identifier:** Phone number (for WhatsApp) or session ID
* **Total Messages:** All messages in conversation
* **User Messages:** Messages that incurred charges
* **Total Cost:** Cost of the conversation
* **Created At:** When conversation started
* **Updated At:** Last activity timestamp

<Info>
  For WhatsApp conversations, you'll also see the customer's phone number and messaging window status (whether free-form replies are available or if templates are required).
</Info>

### Messages Section

Complete conversation timeline showing:

* User messages and assistant responses
* Message content and timestamps
* Chronological conversation flow

### Variables Section

Variables collected during the conversation:

* Pre-chat form data
* Variable names and values

## Managing Conversations

### Deleting Conversations

Remove unwanted conversation records:

1. Select conversation(s) from the table
2. Click the delete action
3. Confirm deletion

<Warning>
  Deleting conversations is permanent and cannot be undone. The conversation history and all associated data will be permanently removed.
</Warning>

### Bulk Actions

Manage multiple conversations at once:

* Select multiple conversations using checkboxes
* Apply bulk delete to clean up test conversations

## Sorting

Click column headers to sort conversations:

* Sort by creation date (newest/oldest first)
* Sort by cost (highest/lowest)
* Sort by message count
* Sort by last update

## Best Practices

* Review conversations regularly to improve assistant responses
* Delete test conversations to keep data clean
* Monitor conversation costs and token usage
* Use filters to find specific conversation types

## Next Steps

* Set up [web widget](/ai-assistants/web-widget) to collect more conversations
* Connect [WhatsApp Business](/whatsapp/overview) for messaging conversations
* Use [test chat](/ai-assistants/test-chat) to test improvements
* Review conversation data regularly to improve assistant performance


# Custom Dashboards
Source: https://docs.autocalls.ai/custom-dashboards/overview

Create personalized dashboards with widgets to track your call metrics and performance

Custom Dashboards let you build tailored analytics views with drag-and-drop widgets. Track the metrics that matter most to your business with stats, charts, and tables.

## What are Custom Dashboards?

Personalized analytics pages you create with widgets displaying your call data. Each dashboard contains multiple widgets showing different data views.

<CardGroup>
  <Card title="Stat Widgets" icon="chart-simple">
    Single metrics like total calls, averages, or success rates
  </Card>

  <Card title="Chart Widgets" icon="chart-line">
    Visual trends with 8 chart types (line, bar, pie, etc.)
  </Card>

  <Card title="Table Widgets" icon="table">
    Detailed records with custom columns and filters
  </Card>
</CardGroup>

## Quick Start

### Create a Dashboard

1. Click **"Create Custom Dashboard"** in sidebar
2. Enter name (e.g., "Sales Performance")
3. Choose icon
4. Click **"Create Dashboard"**

### Add Widgets

**Option 1: Use Presets** (21 ready-made widgets)

1. Click **"Unlock to customize"**
2. Click **"Add"** button
3. Select preset widget (marked with emoji 📊📈📋)
4. Click **"Save"**

**Option 2: Create Custom Widget**

1. Click **"Manage Widgets"** → **"Create New Widget"**
2. Choose type: Statistic, Chart, or Table
3. Configure data source and options
4. Save widget
5. Add to dashboard

## Widget Types

### Stat Widget 📊

Single number with optional comparison and mini-chart.

**Example uses:**

* Total calls this month
* Average call duration
* Success rate percentage

**Key options:**

* Data source: calls, leads, campaigns, assistants, phone\_numbers, sms
* Aggregation: COUNT, SUM, AVG, MAX, MIN
* Color: Primary (Blue), Success (Green), Warning (Orange), Danger (Red), Info (Cyan), Gray
* Label and description text
* Show mini chart (daily trend)
* Compare with previous period (percentage change)
* Date range: Today, Yesterday, Last 7/14/30/60/90 days, Last 6 months, Last year
* Conditions (filters)

### Chart Widget 📈

Visualize trends and distributions.

**Chart types:**

* **Line** - Trends over time
* **Bar** - Compare categories or time periods
* **Area** - Filled trend chart
* **Pie** - Proportions (requires Group By)
* **Donut** - Pie with center hole (requires Group By)
* **Polar Area** - Circular with varying radius (requires Group By)
* **Radar** - Multi-axis comparison
* **Radial Bar** - Single progress/percentage indicator

**Key options:**

* Data source: calls, leads, campaigns, assistants, phone\_numbers, sms
* Aggregation: COUNT, SUM, AVG, MAX, MIN
* Chart type: Line Chart, Bar Chart, Area Chart, Pie Chart, Donut Chart, Polar Area, Radar, Radial Bar
* Color: Primary (Blue), Success (Green), Warning (Orange), Danger (Red), Info (Cyan), Gray
* Group by period: Hourly, Daily, Weekly, Monthly (for time-series)
* Group by field: status, campaign, assistant, any column (for categories)
* Chart height: 200-800px
* Show grid lines, legend, tooltips, data labels, toolbar
* Line curve: smooth, straight, stepline
* Line width: 1-10px
* Gradient (radialBar only)
* Date range: Today, Yesterday, Last 7/14/30/60/90 days, Last 6 months, Last year
* Conditions (filters)

### Table Widget 📋

Detailed records with sortable columns.

**Example uses:**

* Recent calls with details
* Failed calls for review
* Lead contact history

**Key options:**

* Data source: calls, leads, campaigns, assistants, phone\_numbers, sms
* Campaign filter (for leads - enables variable columns)
* Assistant filter (for calls - enables evaluation field columns)
* Column selection: basic, relationships, evaluation fields, lead variables
* Sort by: any basic column
* Sort direction: desc (newest first), asc (oldest first)
* Rows per page: 1-100
* Date range: Today, Yesterday, Last 7/14/30/60/90 days, Last 6 months, Last year
* Conditions (filters)

## Filtering Data

All widgets support powerful filters:

**Date ranges:** Today, Yesterday, Last 7/14/30/60/90 days, Last 6 months, Last year

**Conditions:** Multiple AND filters

* Status equals "completed"
* Duration greater than 60 seconds
* Assistant name equals "Sales Bot"

**Evaluation fields:** Filter by post-call evaluation values

* Column: Extracted Variables
* Extracted Variable Name: Custom variable
* Custom Variable Name: appointment\_booked
* Operator: =
* Variable Value: true

## Layout Management

### Edit Mode

1. Click **"Unlock to customize"**
2. Drag widgets to reorder
3. Resize widgets (1-12 columns wide)
4. Remove widgets with X button
5. Click **"Save"** to persist
6. Click **"Lock"** to exit edit mode

### Best Practices

**Widget sizing:**

* Stats: 3-4 columns (fit 3-4 per row)
* Charts: 6-12 columns
* Tables: 12 columns (full width)

**Layout tips:**

* Put KPIs at top
* Group related metrics
* Place tables at bottom

## Common Use Cases

### Sales Dashboard

* Stat: Successful calls (filter by evaluation field "appointment\_booked")
* Chart: Daily trend of successful calls
* Table: Recent successful calls with appointment details

### Support Quality

* Stat: Average call duration
* Chart: Call status breakdown (pie chart)
* Table: Recent calls with evaluation scores

### Campaign Performance

* Stat: Total campaign calls
* Chart: Calls per campaign (bar chart)
* Table: Top performing campaigns

## Troubleshooting

**Widget shows "No data":**

* Expand date range
* Check filters aren't too restrictive
* Verify you have records

**Slow loading:**

* Reduce widget count (keep under 20)
* Use date range filters
* Clear browser cache

**Dashboard not in sidebar:**

* Refresh page
* Check plan includes feature

<Note>
  For detailed configuration, see individual widget type guides.
</Note>


# Widget Configuration
Source: https://docs.autocalls.ai/custom-dashboards/widget-types

Complete guide for configuring Stat, Chart, and Table widgets with all available options

Learn how to configure each widget type with detailed explanations of every option.

## Creating Widgets

1. Navigate to custom dashboard
2. Click **"Manage Widgets"** then **"Create New Widget"**
3. Select widget type
4. Follow 2-3 step wizard
5. Save and add to dashboard

## Stat Widgets

Single metric display with optional comparison and trend chart.

### Step 1: Basics

**Widget Name**

* Internal identifier for widget list
* Not displayed on dashboard
* Example: "Total Calls This Month"

**Data Table**

* Choose data source: calls, leads, campaigns, assistants, phone\_numbers, sms
* Determines available columns

**Aggregation**

* `COUNT` - Total number of records (no column needed)
* `SUM` - Sum of values (requires column selection)
* `AVG` - Average of values (requires column selection)
* `MAX` - Maximum value (requires column selection)
* `MIN` - Minimum value (requires column selection)

**Column** (if SUM/AVG/MAX/MIN selected)

* Select numeric column to aggregate
* Example: `duration` for average call length
* Not needed for COUNT

### Step 2: Display & Filters

**Label** (required)

* Main heading shown on widget
* Example: "Total Calls"

**Description**

* Optional text below the value
* Hidden if comparison enabled
* Example: "Calls made this month"

**Color**

* primary (blue), success (green), warning (yellow), danger (red), info (cyan), gray
* Choose based on metric type (green for positive, red for negative)

**Show Mini Chart**

* Displays small line chart showing daily trend
* Uses same date range as stat

**Compare with Previous Period**

* Shows percentage change from previous period
* Example: Last 7 days vs previous 7 days
* Displays "+15%" or "-8%" with up/down arrow
* Overrides description field

**Date Range**

* Filter by creation date
* Options: Today, 1, 7, 14, 30, 60, 90, 180, 365 days

**Conditions** (optional)

* Add filters to narrow data
* Multiple conditions combined with AND
* See [Filtering Data](#filtering-data) section

### Examples

**Total Calls**

```
Aggregation: COUNT
Table: calls
Label: "Total Calls"
Description: "Last 30 days"
Color: primary
Date Range: 30 days
```

**Average Call Duration**

```
Aggregation: AVG
Table: calls
Column: duration
Label: "Avg Duration"
Color: info
Show Mini Chart: Yes
Date Range: 30 days
```

**Successful Appointments**

```
Aggregation: COUNT
Table: calls
Label: "Appointments Booked"
Color: success
Compare: Yes
Date Range: 7 days
Conditions:
  - status = completed
  - evaluation.appointment_booked = true
```

## Chart Widgets

Visualize trends with 8 chart types.

### Step 1: Basics

Same as Stat widgets, plus:

**Chart Type**

* `line` - Trends over time
* `bar` - Compare categories or time periods
* `area` - Filled trend chart
* `pie` - Proportions (requires Group By)
* `donut` - Pie with center hole (requires Group By)
* `polarArea` - Circular with varying radius (requires Group By)
* `radar` - Multi-axis comparison
* `radialBar` - Single progress indicator

### Step 2: Display & Filters

**Label** (required)

* Chart title

**Description**

* Optional subheading text below the chart
* Example: "Last 30 days performance"

**Color**

* Chart primary color
* For pie/donut, uses multi-color palette (blue, green, orange, red, purple, pink)

**Date Range**

* Same as stats

**Group By** OR **Group By Period** (mutually exclusive)

**Group By** - Categorical grouping

* Group data by column values
* Examples: Status, Campaign Id, Assistant Name
* **Required** for pie/donut/polarArea charts
* Optional for bar/radar charts
* **Cannot use** with Group By Period

**Group By Period** - Time-based grouping

* Group by time buckets
* Options: hour, day, week, month
* Used for line/bar/area charts
* **Cannot use** with Group By

**Conditions**

* Same as stats

### Step 3: Advanced (Charts Only)

**Show Grid Lines** (line/bar/area only)

* Background horizontal/vertical lines
* Helps read exact values
* Default: Yes

**Show Legend**

* Color-coded labels
* Default: Yes for pie/donut/polarArea, No for others
* Position: Bottom of chart

**Show Tooltips**

* Hover popups with exact values
* Default: Yes (recommended)

**Show Data Labels**

* Values displayed directly on chart elements
* Default: Yes for pie/donut/polarArea, No for others
* Can clutter line/bar charts

**Show Toolbar** (line/bar/area only)

* Zoom and download controls
* Default: No

**Line Curve** (line/area only)

* `smooth` - Rounded curves (default, visually appealing)
* `straight` - Direct lines (precise)
* `stepline` - Step-wise (good for discrete events)

**Line Width** (line/bar/area only)

* Thickness in pixels (1-10)
* Default: 2px

**Chart Height**

* Vertical space in pixels (200-800)
* Default: 300px
* Taller charts better for more data points

**Enable Gradient** (radialBar only)

* Color gradient effect
* Default: No

**Gradient Color** (if gradient enabled)

* End color for gradient
* Default: Green (#10b981)

**Calculate as Percentage** (radialBar only)

* Automatically calculates percentage from conditions
* Formula: (conditions met / total) × 100
* **Requires:** At least one condition must be added first
* Example: Condition "status = completed" calculates completed leads / total leads × 100
* Appears after adding conditions in Step 2

**Show Footer with Numbers** (radialBar only)

* Displays "X achieved / Y total" below the radialBar chart
* Only visible when "Calculate as Percentage" is enabled
* Shows exact numbers alongside the percentage
* Example footer: "150 achieved / 1,000 total"

**Start Angle** (radialBar only)

* Where the arc begins in degrees (-360° to 360°)
* Default: -140°
* Common values: -140° (default), -90° (left semicircle), 0° (bottom)

**End Angle** (radialBar only)

* Where the arc ends in degrees (-360° to 360°)
* Default: 130°
* **Validation:** Total arc (end - start) cannot exceed 360°
* Common values: 130° (default), 90° (right semicircle), 180° (half circle), 270° (three-quarters)

**Hollow Size** (radialBar only)

* Inner circle size as percentage (0-100%)
* Default: 60%
* Higher value = thinner ring, lower value = thicker ring

**Dash Array** (radialBar only)

* Spacing for dashed ring pattern (0-50)
* Default: 10
* 0 = solid line, higher numbers = more spacing between dashes

### Chart Type Guide

**Line Chart**

* **Use for:** Daily/weekly trends, continuous data
* **Requires:** Group By Period
* **Example:** Calls per day last 30 days

**Bar Chart**

* **Use for:** Category comparison, time periods
* **Can use:** Group By (categories) OR Group By Period (time)
* **Example:** Calls per campaign, hourly distribution

**Area Chart**

* **Use for:** Same as line, emphasizes volume
* **Requires:** Group By Period
* **Example:** Call volume trend

**Pie/Donut Chart**

* **Use for:** Proportions, percentages
* **Requires:** Group By (NOT Group By Period)
* **Example:** Call status breakdown

**Polar Area**

* **Use for:** Like pie but shows magnitude via radius
* **Requires:** Group By
* **Example:** Campaign contribution

**Radar Chart**

* **Use for:** Multi-variable comparison
* **Requires:** Group By
* **Example:** Performance across metrics

**Radial Bar**

* **Use for:** Circular progress indicators showing percentages (0-100%)
* **Does not use:** Group By or Group By Period
* **Percentage Calculation:** Add conditions, then enable "Calculate as Percentage" to automatically compute (conditions met / total) × 100
* **Example:** Lead conversion rate (15%), SMS delivery success (82.8%), goal completion

### Examples

**Daily Call Volume (Line)**

```
Table: calls
Aggregation: COUNT
Chart Type: line
Label: "Daily Calls"
Group By Period: day
Show Grid: Yes
Stroke Curve: smooth
Date Range: 30 days
```

**Status Breakdown (Pie)**

```
Table: calls
Aggregation: COUNT
Chart Type: pie
Label: "Call Status"
Group By: status
Show Legend: Yes
Show Data Labels: Yes
Date Range: 7 days
```

**Hourly Pattern (Bar)**

```
Table: calls
Aggregation: COUNT
Chart Type: bar
Label: "Calls By Hour"
Group By Period: hour
Date Range: 7 days
```

**Campaign Comparison (Bar)**

```
Table: calls
Aggregation: COUNT
Chart Type: bar
Label: "Calls Per Campaign"
Group By: campaign.name
Date Range: 30 days
```

**Lead Conversion Rate (Radial Bar with Percentage)**

```
Table: leads
Aggregation: COUNT
Chart Type: radialBar
Label: "Conversion Rate"
Description: "Completed leads"
Color: success
Date Range: 30 days

Step 2 - Conditions:
  Field: status
  Operator: =
  Value: completed

Step 2 - Percentage (appears after adding condition):
  Calculate as Percentage: Yes
  Show Footer with Numbers: Yes

Step 3 - Advanced (optional):
  Start Angle: -140°
  End Angle: 130°
  Hollow Size: 60%
  Dash Array: 10

How it works:
  - Counts leads where status = completed (e.g., 150)
  - Counts total leads (e.g., 1,000)
  - Calculates: 150 / 1,000 × 100 = 15%
  - Displays: "15%" with footer "150 achieved / 1,000 total"
```

**SMS Delivery Success (Radial Bar with Gradient)**

```
Table: sms
Aggregation: COUNT
Chart Type: radialBar
Label: "SMS Delivered"
Description: "Delivery success rate"
Color: info
Date Range: 7 days

Step 2 - Conditions:
  Field: status
  Operator: =
  Value: delivered

Step 2 - Percentage:
  Calculate as Percentage: Yes
  Show Footer with Numbers: Yes

Step 3 - Advanced:
  Enable Gradient: Yes
  Gradient To Color: #10b981 (green)
  Start Angle: -90°
  End Angle: 270° (creates three-quarter circle)
  Hollow Size: 55%
  Dash Array: 12

Result: "82.8%" with footer "120 achieved / 145 total"
Visual: Blue to green gradient, three-quarter circle
```

**Quality Calls (Multiple Conditions)**

```
Table: calls
Aggregation: COUNT
Chart Type: radialBar
Label: "Quality Calls"
Description: "Long completed outbound calls"
Color: success
Date Range: 30 days

Step 2 - Conditions (all must be true):
  Condition 1:
    Field: status
    Operator: =
    Value: completed

  Condition 2:
    Field: duration
    Operator: >
    Value: 180

  Condition 3:
    Field: type
    Operator: =
    Value: outbound

Step 2 - Percentage:
  Calculate as Percentage: Yes
  Show Footer with Numbers: Yes

Step 3 - Advanced:
  Enable Gradient: Yes
  Gradient To Color: #3b82f6
  Dash Array: 8

How it works:
  - Counts calls meeting ALL three conditions (e.g., 45)
  - Counts total calls (e.g., 100)
  - Calculates: 45 / 100 × 100 = 45%
  - Displays: "45%" with footer "45 achieved / 100 total"
```

**Qualified Leads (Semicircle Style)**

```
Table: leads
Aggregation: COUNT
Chart Type: radialBar
Label: "Qualified Leads"
Color: info
Date Range: 30 days

Step 2 - Conditions:
  Field: status
  Operator: =
  Value: scheduled

Step 2 - Percentage:
  Calculate as Percentage: Yes
  Show Footer with Numbers: Yes

Step 3 - Advanced (semicircle design):
  Enable Gradient: Yes
  Gradient To Color: #10b981
  Start Angle: -90°
  End Angle: 90° (creates perfect semicircle)
  Hollow Size: 70% (thinner ring)
  Dash Array: 0 (solid line)

Result: "2.2%" with footer "4,841 achieved / 220,073 total"
Visual: Clean semicircle from left to right, blue to green gradient
```

## Table Widgets

Display detailed records with custom columns.

### Step 1: Basics

**Data Table**

* Choose source: calls, leads, campaigns, assistants, phone\_numbers, sms

**Campaign Filter** (leads table only)

* Select campaign to:
  * Filter table to that campaign
  * Enable custom variable columns
* Optional

**Assistant Filter** (calls table only)

* Select assistant to:
  * Filter table to that assistant
  * Enable evaluation field columns
* Optional

**Column Selection**

* Basic columns: Id, Status, Created At, etc.
* Relationship columns: Assistant Name, Campaign Name
* Evaluation fields: evaluation. (if assistant selected)
* Lead variables: variables. (if campaign selected)
* Default if none selected: Id, Status, Created At

### Step 2: Display & Filters

**Label** (required)

* Table heading

**Description**

* Optional subheading

**Date Range**

* Same as stats/charts

**Sort By**

* Default sort column
* Only simple columns (not relationships)
* Default: created\_at

**Sort Direction**

* desc (newest first) - default
* asc (oldest first)

**Rows Per Page**

* Number of rows to display (1-100)
* Default: 10

**Conditions**

* Same as stats/charts

### Interactive Features

**Clickable Rows**

* Table rows are clickable
* Automatically links to detail/edit page for the record
* Works for: Calls, Leads, Campaigns, Assistants

**Live Date Filter**

* Change date range directly on the widget
* Overrides the configured default date range
* Useful for exploring different time periods

**Status Filter**

* Multi-select dropdown to filter by status
* Available for: Calls, Leads, Campaigns, Assistants, SMS
* Select multiple statuses at once

**Text Display**

* Long text automatically truncates at 50 characters
* Hover over truncated text shows full content in tooltip

### Column Types

**Phone Number Columns**

* International format (+1 555 123 4567)
* Country flag prefix
* Examples: client\_phone\_number, phone\_number

**Status Columns**

* Colored badges
* Examples: status field on any table

**Date Columns**

* "3 hours ago" format
* Hover shows full datetime
* Examples: created\_at, updated\_at

**Evaluation Columns** (calls table with assistant)

* Boolean fields: checkmark or X with green/red badge
* Non-boolean fields: value with gray badge
* Hover shows field description
* Format: evaluation.

**Variable Columns** (leads table with campaign)

* Custom lead data
* Format: variables.
* Examples: customer\_name, company

**Relationship Columns**

* Access related data
* Examples: Assistant Name, Campaign Name
* Cannot sort by these

### Examples

**Recent Calls**

```
Table: calls
Columns:
  - Client Phone Number
  - Assistant Name
  - Duration
  - Status
  - Created At
Sort: Created At desc
Rows: 25
Date Range: 7 days
```

**Successful Appointments**

```
Table: calls
Assistant: [Select to load fields]
Columns:
  - Client Phone Number
  - Assistant Name
  - evaluation.appointment_booked
  - Created At
Sort: Created At desc
Rows: 50
Date Range: 30 days
Conditions:
  - Status = completed
  - Column: Extracted Variables
    Extracted Variable Name: Custom variable
    Custom Variable Name: appointment_booked
    Operator: =
    Variable Value: true
```

## Filtering Data

All widgets support conditions to filter data.

### Operators

* `=` - Equals
* `!=` - Not equals
* `>` - Greater than
* `>=` - Greater or equal
* `<` - Less than
* `<=` - Less or equal
* `like` - Contains text
* `in` - One of (comma-separated)
* `not in` - Not one of
* `is null` - No value
* `is not null` - Has value

### Basic Filtering

**Status Filter**

```
Column: Status
Operator: =
Value: completed
```

**Duration Filter**

```
Column: Duration
Operator: >
Value: 60
```

**Multiple Values**

```
Column: Status
Operator: in
Value: completed,in-progress
```

### Evaluation Field Filtering

Filter by post-call evaluation values.

**Setup:**

1. Column: Extracted Variables
2. Extracted Variable Name: Status or Custom variable
3. If Custom variable: Enter field name in Custom Variable Name
4. Variable Value: true/false for booleans, or any + custom value

**Boolean Example - Appointment Booked**

```
Column: Extracted Variables
Extracted Variable Name: Custom variable
Custom Variable Name: appointment_booked
Operator: =
Variable Value: true
```

**Non-Boolean Example - Sentiment**

```
Column: Extracted Variables
Extracted Variable Name: Custom variable
Custom Variable Name: sentiment
Operator: =
Variable Value: any
Custom Value: positive
```

**Check Field Exists**

```
Column: Extracted Variables
Extracted Variable Name: Custom variable
Custom Variable Name: interested
Operator: =
Variable Value: any
```

### Multiple Conditions

Conditions combined with AND:

```
Filter for successful long calls:
Condition 1:
  - Column: Status
  - Operator: =
  - Value: completed

Condition 2:
  - Column: Duration
  - Operator: >
  - Value: 120

Condition 3:
  - Column: Extracted Variables
  - Extracted Variable Name: Custom variable
  - Custom Variable Name: appointment_booked
  - Operator: =
  - Variable Value: true
```

## Best Practices

### Widget Naming

Use descriptive internal names:

* ✅ "Sales Calls - Last 30 Days"
* ✅ "Support Duration Average"
* ❌ "Widget 1"

### Date Ranges

Match range to use case:

* **Today:** Real-time monitoring
* **7 days:** Weekly performance
* **30 days:** Monthly trends
* **90+ days:** Long-term analysis

### Colors

Strategic color usage:

* **Green (success):** Positive metrics
* **Red (danger):** Alert metrics
* **Blue (primary):** Neutral metrics
* **Yellow (warning):** Attention needed
* **Gray (info):** Secondary info

### Performance

Keep dashboards fast:

* Use date range filters
* Limit widgets per dashboard to under 20
* Use COUNT when possible (faster)
* Avoid very long date ranges

## Troubleshooting

**Widget shows "No data"**

* Expand date range
* Remove/adjust filters
* Verify table has records

**Evaluation fields not showing**

* Select assistant in widget config
* Ensure assistant has post-call schema
* Check field names match

**Chart shows empty**

* Pie/donut: Must use Group By (not Period)
* Line/area: Must use Group By Period (not Category)
* Check date range includes data

**Table missing columns**

* Relationship columns need related records
* Evaluation columns need assistant selection
* Variable columns need campaign selection

**"Group By required" error**

* Pie/donut/polarArea charts MUST have Group By
* Cannot use Group By Period with these chart types

**Cannot sort by column**

* Relationship columns (with .) not sortable
* Evaluation fields not sortable
* Use basic columns for sorting

<Note>
  For dashboard creation and layout management, see [Custom Dashboards Overview](/custom-dashboards/overview).
</Note>


# Core Concepts
Source: https://docs.autocalls.ai/getting-started/core-concepts

Learn the fundamental building blocks of Autocalls.ai, including system prompts, voices, and AI assistants

Welcome to the fundamentals of Autocalls.ai. Here, we explore the essential building blocks that you need to understand before configuring your AI assistant and calls.

## 1. System Prompt & Initial Message

**System Prompt**

* The "brain" of your AI assistant. You write a short (or long) set of instructions that guide the assistant's behavior and tone of voice.
* This includes any important business info, disclaimers, or how you want the AI to handle edge cases.
* For example: *"You are a helpful phone assistant for XYZ Company, you greet in a friendly manner, confirm the caller's info, etc."*

**Initial Message**

* The very first thing the AI says.
* Typically short, like "Hello, thanks for calling XYZ Company!"

## 2. Voices

* Autocalls.ai integrates with **ElevenLabs** voices for natural-sounding speech.
* You can **clone** your own voice by providing audio samples or pick from built-in voices.
* Each voice can have adjustable parameters like speech speed, filler usage, or accent (if available).

## 3. Putting It All Together

* An **AI Assistant** is built by combining a system prompt, an initial message, and a chosen voice.
* Optionally, you add tools (like "transfer call" or "end call").
* Once the assistant is set, you assign it to a phone number (for inbound) or a campaign (for outbound).

**Next Steps**

* Learn how [call minutes and billing](/getting-started/understanding-billing) work to plan your usage.
* Or, jump to [AI Assistants Overview](/ai-assistants/what-is-ai-assistant) to start building your first assistant.


# Understanding Call Minutes & Billing
Source: https://docs.autocalls.ai/getting-started/understanding-billing

Learn how Autocalls.ai billing works, including call minutes calculation, phone number rentals, and usage monitoring

Autocalls.ai operates on a **usage-based** model. You pay primarily for two things:

1. The **minutes** your AI spends in calls.
2. Any **dedicated phone number** rentals.

## 1. Included Minutes vs. Pay-as-You-Go

* **Included Minutes**: Some plans may come with a set of monthly minutes. These are consumed first.
* **Pay-as-You-Go**: If you exceed included minutes (or if you're on a usage-based plan), you pay for each additional minute used.

## 2. How We Calculate Minutes

* **Minimum Charge**: Every call has a minimum AI charge of **30 seconds (0.5 min)**. A call shorter than 30 seconds is still billed as 30 seconds.
* **Per-Second Billing**: Beyond 30 seconds, Autocalls.ai bills by the second (converted to minutes). For example, a 90-second call is 1.5 minutes.

## 3. Monthly Usage & Purchasing Extra

* **Monthly Reset**: If your plan includes minutes, those reset monthly on your billing date.
* **Buying Add-Ons**: You can purchase extra minute bundles if you expect a spike in call volume.

## 4. Additional Costs

* **Phone Number Rental**: A monthly fee for each dedicated inbound/outbound number you rent (varies by region).
* **Possible Carrier Surcharges**: Some countries may have unique taxes or surcharges—check the [Costs & Pricing](/pricing/overview) section for more details.

## 5. Monitoring Usage

* **Dashboard**: The platform displays your current usage, how many minutes are left, and your estimated cost so far.
* **Notifications**: You can set up alerts (e.g., "Email me when I hit 80% of monthly minutes") using the no-code automation platform.

**Next Steps**

* Check out our [Costs & Pricing](/pricing/overview) section for a deeper breakdown of number rentals, international rates, inbound vs. outbound cost differences, and more.
* Or proceed to [AI Assistants Overview](/ai-assistants/what-is-ai-assistant) to build your first agent.


# Configuring the Inbound Assistant
Source: https://docs.autocalls.ai/inbound-calls/configuring

Set up your inbound AI assistant with prompts, voices, and tools for handling incoming calls

An "Inbound Assistant" is simply an AI assistant set to **inbound** mode. Key steps:

1. **Prompt & Voice**

   * Provide a clear system prompt. Example:\
     *"You are the Support Bot for Acme Inc. Greet politely, ask for the customer's need, and attempt to answer basic FAQs."*
   * Choose a voice from the built-in library or a cloned voice.

2. **Initial Message**

   * The first line of dialogue once the AI picks up.
   * Example: *"Hi, thank you for calling Acme Inc. How may I help you?"*

3. **Add Tools (Optional)**

   * **Transfer**: If the caller needs a human agent.
   * **End Call**: Condition to end the call politely.
   * **Appointment Scheduler**: If you want them to book a slot on your calendar.

4. **Call Flow**

   * In the system prompt, mention potential dialogues, e.g., "If they mention billing, ask for their invoice number."

5. **Save & Test**
   * Dial the inbound number from your cell phone.
   * Confirm the AI greets and responds according to your instructions.

***

**Tip:** Revisit your assistant's settings regularly to improve the conversation flow—especially if you see frequent hang-ups or missed info.


# Inbound Call Insights
Source: https://docs.autocalls.ai/inbound-calls/insights

Access and analyze inbound call data, including transcripts, recordings, and automation triggers

After an inbound call, Autocalls.ai provides transcripts, analytics, and possible automation triggers.

## 1. Recording & Transcription

* **Recording**: Typically saved in the call logs, so you can replay.
* **Transcription**: The AI's recognized text, which is used to generate its responses.

## 2. Post-Call Data (Summary & Extracted Variables)

* The AI can store or forward call info (e.g., name, reason for calling) to a connected CRM or spreadsheet.
* Summaries may include "intent" or "call outcome."

## 3. Automation Triggers

* Using the built-in no-code platform, you can do things like:
  1. **Email or Slack** the transcript to your team.
  2. **Log** the call outcome in Google Sheets.
  3. **Notify** a human agent if follow-up is needed.

## 4. Viewing Insights

* In your Autocalls.ai dashboard, go to **Calls** or **History**.
  * Filter by inbound calls.
  * Click a specific call to see the transcript, recording, or final notes.

***

**Note:** For advanced analytics (like call sentiment or deeper classification), watch out for upcoming features or use the webhook/API to feed transcripts into external tools.


# Inbound Calls Overview
Source: https://docs.autocalls.ai/inbound-calls/overview

Learn how AI assistants handle incoming calls, from answering to call completion and analytics

When someone dials your dedicated (or SIP-integrated) number, Autocalls.ai can answer automatically through an AI Assistant. This section covers the big-picture flow of inbound calling:

1. **Caller Dials Your Number**

   * A local, international, or toll-free line assigned to your AI assistant.

2. **AI Assistant Answers**

   * Greets the caller using your configured voice and initial message.
   * Follows the **system prompt** to handle inquiries or gather information.

3. **Optional Actions**

   * Transfer to a human operator (if configured).
   * Schedule appointments, check order statuses, or collect data for later use.

4. **Call Completion**
   * AI ends the call politely or transfers to a queue/agent if needed.
   * You get transcripts and call analytics afterward.

***

**Tip:** Start by renting or provisioning a phone number and linking it to an inbound-type AI Assistant.


# Provisioning & Managing Phone Numbers
Source: https://docs.autocalls.ai/inbound-calls/provisioning

Learn how to provision, assign, and manage phone numbers for inbound AI calls

If you haven't already, check out our [Phone Numbers](/phone-numbers/types) section to learn how to obtain or integrate a number. Once you have a number:

1. **Assign It to Your AI Assistant**

   * Go to **Assistants** > **(Your Inbound Assistant)**.
   * Under **Phone Number**, pick the number you want to use.

2. **Verify Functionality**

   * Test by calling the number from an external phone.
   * The AI should answer with your configured greeting.

3. **Monitoring Inbound Lines**
   * In the **Phone Numbers** page, you can see active lines, monthly cost, and usage.
   * Release lines you no longer need to avoid extra rental fees.

## Handling Country-Specific Requirements

Some regions may require:

* **Local address or business registration**
* **ID documents** for toll-free or special lines

If so, you'll be prompted to upload documents for **custom provisioning** before your number is activated.


# How It Works (Quick Overview)
Source: https://docs.autocalls.ai/introduction/how-it-works

Understand the technical flow of how Autocalls.ai processes and handles phone conversations using AI

Autocalls.ai blends **AI voice recognition** with **LLM-based replies** to conduct live phone conversations. Below is a simplified flow:

1. **Caller or Lead is Dialed**

   * **Inbound**: A customer dials your assigned phone number.
   * **Outbound**: Autocalls.ai's system calls a list of phone numbers from your campaign.

2. **Speech Recognition**\
   The AI listens to what the person says and transcribes it into text in real time.

3. **LLM Decision**\
   Autocalls.ai uses a large language model (LLM) and your configured "system prompt" to craft a reply or decide the next action (like transferring the call).

4. **Voice Output**\
   The AI's response is converted to natural-sounding speech via our voice engine (ElevenLabs voices).

5. **Result & Actions**

   * For **Inbound**: The AI may answer questions, verify info, or take a message.
   * For **Outbound**: The AI can pitch a product, qualify leads, or transfer interested callers to a human agent.

6. **Data & Reporting**\
   You get transcripts, call recordings, call outcomes (like "no answer" or "success"), and the ability to automate follow-up actions.

## Distinctions: Inbound vs. Outbound

* **Inbound**

  * Caller dials a number you rented or integrated.
  * AI picks up, greets, and handles queries or routes the caller if needed.

* **Outbound**
  * You upload or sync leads.
  * AI dials each number, follows your call script, possibly transfers if the lead is interested.

## Next Steps

* Learn about [**Key Terminology**](/introduction/key-terminology) (like "AI Assistant," "Campaign," etc.).
* Jump into [**Getting Started**](/getting-started) to set up your first AI assistant.


# Key Terminology
Source: https://docs.autocalls.ai/introduction/key-terminology

Essential terms and concepts you need to know to use Autocalls.ai effectively

Understanding these terms will help you navigate Autocalls.ai more easily:

## [AI Assistant / Agent](/ai-assistants/what-is-ai-assistant)

A customizable bot you configure to handle inbound or outbound calls. Defines conversation style, voice, and behavior via a "system prompt."

## [Campaign (Outbound)](/campaigns/index)

A sequence or batch of calls to a list of contacts or leads. You can upload a CSV, connect Google Sheets, or integrate your CRM to launch these calls.

## [Inbound Number](/phone-numbers/types)

A dedicated phone number that customers dial to reach your AI assistant. You can get one from the platform or integrate via SIP/PBX.

## [Outbound Caller ID](/outbound-calls/caller-id)

The number displayed on the customer's phone when your AI calls them. You can rent one or verify an existing number to use as Caller ID.

## [No-Code Automation Platform](/automation-platform/introduction)

Autocalls.ai's built-in workflow platform, similar to Zapier/Make. It lets you connect triggers (like "call ended") to actions (like "send an email" or "update a Google Sheet") without writing code.

## [Tools / Integrations](/ai-assistants/settings/prompt-and-tools#default-tools)

Refers to the specialized features your AI assistant can use, like transferring a call, ending a call, scheduling an appointment, or webhooks to external apps.

## [Knowledge Base](/conversation-design/knowledge-bases)

A collection of documents (PDFs, websites, text files) that your AI assistant can reference during calls to provide accurate information and answer customer questions.

## [Post-Call Variables](/ai-assistants/settings/post-call-actions#post-call-variables)

Data extracted by AI after each call (like `status`, `summary`, `formatted_transcript`) that can be used in automations and follow-up actions.

## [Call Variables](/ai-assistants/settings/prompt-and-tools#call-variables)

Dynamic data that personalizes each call (like `customer_name`, `email`, `company`) and can be used in system prompts and automations.

## [Lead Status](/leads/index)

The current state of a lead in your system: Created, Scheduled, Processing, Completed, Rescheduled, or Max Retries.

## [Campaign Status](/campaigns/index)

The current state of a campaign: Draft, In Progress, Paused, or Completed.

## [Webhook](/api-reference/webhooks/post-call-webhook)

A URL endpoint that receives data when specific events occur (like call endings), enabling real-time integrations with external systems.

## [SIP Integration](/provisioning/sip-trunking/sip-integration)

A method to connect your existing phone system or VOIP provider with Autocalls.ai without renting new numbers.

***

**Tip:** Keep these definitions in mind as you proceed through the docs. They'll pop up in various setup steps or feature explanations.


# What is Autocalls.ai?
Source: https://docs.autocalls.ai/introduction/what-is-autocalls

Learn about Autocalls.ai, a voice automation platform that uses AI to handle real-time phone conversations

Autocalls.ai is a voice automation platform that leverages AI to handle phone calls in real time. It allows you to create AI-driven assistants (or "agents") that can speak with your customers over the phone—both inbound and outbound.

## Core Features

* **Inbound & Outbound Calls**\
  Handle both incoming support calls or automated outbound campaigns to reach leads and customers.

* **AI-Powered Conversations**\
  Uses advanced language models (LLMs) and speech recognition for natural-sounding interactions.

* **No-Code Flows**\
  Built-in automation platform to connect with Google Sheets, CRMs, calendars, and more—no coding required.

## Key Benefits

* **24/7 Availability**\
  Your AI agent can handle calls around the clock, reducing missed calls or wait times.

* **Scalability**\
  The same number can handle multiple calls in parallel, perfect for high-volume scenarios.

* **Time & Cost Savings**\
  Free up human agents for complex tasks while the AI handles repetitive or basic inquiries.

## Why Choose Autocalls.ai?

* **Real-Time Phone Call Automation**: The AI transcribes, understands, and responds live, just like a human agent.
* **Multiple Language & Voice Options**: Built-in library or custom voice cloning, plus support for many languages.
* **Easy Setup**: Create your first assistant in minutes. Testing and iterating are straightforward.


# Importing Leads
Source: https://docs.autocalls.ai/leads/importing-leads

Import leads from CSV and Excel files with validation and error handling

Import large numbers of leads from CSV or Excel files with automatic validation, background processing, and comprehensive error reporting.

## Import Process Overview

The lead import system supports:

* **CSV and Excel files** (.csv, .xlsx, .xls)
* **Background processing** for large files
* **Automatic validation** with error reporting
* **Secondary contacts** in same import
* **Variable mapping** from assistant configuration

## Preparing Your Import File

### Required Columns

Your import file must include:

* **phone\_number:** Primary contact phone number (required)
* **Variables:** Columns matching your [assistant's configured variables](/ai-assistants/settings/prompt-and-tools#call-variables)

### Optional Columns

* **Secondary contact columns:** Additional phone numbers
* **Variable overrides:** Custom values for specific leads

### File Format Example

```csv theme={null}
phone_number,customer_name,company,budget_range,secondary_phone_1,secondary_phone_2
+14155551234,John Smith,ABC Corp,10k-50k,+14155551235,+14155551236
+14155557890,Jane Doe,XYZ Inc,50k-100k,+14155557891,
+14155554567,Bob Johnson,Tech Start,5k-10k,,
```

## Import Configuration

### 1. Select Campaign

Choose the target campaign from the dropdown. The assistant's variables will determine what columns are expected during mapping.

### 2. Secondary Contacts

Select how many secondary phone numbers per lead (0-10). If your file contains additional phone numbers beyond the primary contact, specify the count here.

### 3. Phone Number Format

Choose the format of your phone numbers:

**International Format (Recommended)**

* Numbers already include country code with + prefix
* Example: `+40741234567`, `+14155551234`
* No country selection needed
* Can mix multiple countries in same file

**National Format**

* Numbers without country code prefix
* Example: `0741234567`, `7775551234`
* **Must select country code** during import
* **Important:** Separate your file by country - all numbers must be from the same country per file
* System will add the selected country code to all numbers

<Warning>
  When using national format, you must import one file per country. Do not mix numbers from different countries in the same file.
</Warning>

### 4. Country Code Selection

Only appears when "National Format" is selected. Choose the country that matches all phone numbers in your file. The system will automatically prepend the country code to all numbers.

## Import Steps

### 1. Start Import Process

1. **Navigate to Leads** section or Campaign leads tab
2. **Click "Import Leads"** button
3. **Select campaign** for lead assignment
4. **Download sample** file to see expected format

### 2. Upload and Map Columns

1. **Choose file:** Select your CSV or Excel file
2. **Column mapping:** Map your file columns to system fields:
   * **Phone Number (required):** Select the column containing phone numbers
   * **Assistant variables:** Map each variable to its corresponding column
   * **Secondary contacts:** If configured, map secondary phone numbers and variables
3. **Auto-detection:** System auto-detects mappings based on common header names
4. **Review and import:** Confirm mappings and click "Import" to begin

### 3. Background Processing

* **Queue processing:** Large files processed in background
* **Progress tracking:** Import status updates automatically
* **Notification:** Email notification when import completes
* **Error reporting:** Download report of any failed rows

## Validation Rules

### Phone Number Validation

* **Format checking:** International format preferred (+1234567890)
* **Duplicate detection:** Prevents duplicate phone numbers
* **Invalid numbers:** Automatically flagged and skipped

### Variable Validation

* **Required fields:** Variables marked as required must have values
* **Data types:** Text, number, boolean validation where applicable
* **Length limits:** Maximum character limits enforced

### Secondary Contact Validation

* **Phone format:** Same validation as primary numbers
* **Unique numbers:** Secondary contacts must differ from primary
* **Variable consistency:** Secondary contact variables validated independently

## Error Handling

### Automatic Error Handling

The import system automatically handles validation errors:

* **Valid rows imported:** Successfully validated leads are added to the campaign
* **Invalid rows skipped:** Rows that fail validation are automatically excluded
* **Error report generated:** Detailed report of all failed rows is created
* **Partial success:** Import completes successfully with all valid leads, failed rows are recorded

### Common Validation Errors

* **Invalid phone numbers:** Incorrect format or impossible numbers
* **Missing required fields:** Empty values for required variables
* **Duplicate phone numbers:** Phone number already exists in system
* **File format issues:** Corrupted or unsupported file format

### Error Report Download

After import completion:

* **Download link** provided in notification
* **Detailed error descriptions** for each failed row
* **Correction guidance** for fixing issues
* **Re-import capability** with corrected data

## Secondary Contacts Import

### Multiple Phone Numbers per Lead

Include additional columns for secondary contacts:

```csv theme={null}
phone_number,customer_name,secondary_phone_1,secondary_phone_2,secondary_phone_3
+14155551234,John Smith,+14155551235,+14155551236,+14155551237
```

### Secondary Contact Variables

Add variables specific to secondary contacts:

```csv theme={null}
phone_number,customer_name,secondary_phone_1,secondary_1_name,secondary_1_role
+14155551234,John Smith,+14155551235,Jane Smith,Decision Maker
```

### Contact Ordering

* **Primary contact:** Always called first
* **Secondary order:** Called in column order (secondary\_phone\_1, then secondary\_phone\_2, etc.)
* **Campaign coordination:** Respects campaign retry settings between contacts

## Large File Handling

### Background Processing

* **Automatic queuing:** Files over 1000 rows processed in background
* **Memory efficiency:** Streaming processing prevents timeouts
* **Progress tracking:** Real-time status updates
* **System performance:** No impact on platform performance during import

### Notification System

* **Email notifications:** Sent when import completes
* **Success summary:** Number of leads imported successfully
* **Error summary:** Count and details of failed rows
* **Download links:** Access to error reports and imported data

### Processing Time

* **Small files (\< 100 rows):** Usually complete within 1 minute
* **Medium files (100-1000 rows):** 2-5 minutes typical
* **Large files (1000+ rows):** 10-30 minutes depending on complexity
* **Very large files (10k+ rows):** May take several hours

## Best Practices

* **Use sample file:** Download provided template for correct format
* **Phone format:** International format without separators (+1234567890)
* **Clean data:** Remove empty rows and validate content
* **Test first:** Start with small batch to verify format
* **Match variables:** Ensure columns align with assistant configuration

<Note>
  For detailed troubleshooting and common import issues, see [Leads Troubleshooting](/troubleshooting/leads).
</Note>

<Note>
  For information about managing imported leads, see [Managing Leads](/leads/managing-leads).
</Note>


# Leads Overview
Source: https://docs.autocalls.ai/leads/index

Manage your campaign contacts with primary leads, secondary contacts, and custom variables

Leads are the contacts that your campaigns will call. Each lead can have multiple phone numbers (secondary contacts) and custom variables that your AI assistant can use during conversations.

## What are Leads?

Leads represent the people or businesses you want to contact through your campaigns. The lead system supports:

<CardGroup>
  <Card title="Primary Contacts" icon="user">
    **Main contact** for each lead

    The primary phone number and contact information
  </Card>

  <Card title="Secondary Contacts" icon="users">
    **Additional phone numbers** for the same lead

    Backup contacts, decision makers, or alternative numbers
  </Card>

  <Card title="Custom Variables" icon="code">
    **Personalized information** for AI conversations

    Names, preferences, history, or any data your assistant needs
  </Card>

  <Card title="Status Tracking" icon="chart-line">
    **Progress monitoring** through campaign lifecycle

    Track call attempts, completions, and retry status
  </Card>
</CardGroup>

## Lead Status System

Every lead moves through different statuses during campaign execution:

<AccordionGroup>
  <Accordion title="Created" icon="plus">
    **Ready to call** - Lead is queued for first contact attempt
  </Accordion>

  <Accordion title="Scheduled" icon="calendar">
    **Queued for retry** - Scheduled for next call attempt based on campaign settings
  </Accordion>

  <Accordion title="Processing" icon="phone">
    **Currently being called** - Call is in progress
  </Accordion>

  <Accordion title="Rescheduled" icon="clock">
    **Waiting for retry** - Will be called again after retry interval
  </Accordion>

  <Accordion title="Max Retries" icon="ban">
    **Retry limit reached** - Maximum call attempts exceeded
  </Accordion>

  <Accordion title="Completed" icon="check">
    **Successfully contacted** - Call completed or goal achieved
  </Accordion>
</AccordionGroup>

## Primary vs Secondary Contacts

### Primary Contacts

* **Main lead record** with complete information
* **First to be called** in campaign sequence
* **Inherits campaign variables** from assistant settings
* **Controls overall lead status** and completion

### Secondary Contacts

* **Additional phone numbers** for the same person/business
* **Called if primary doesn't answer** (based on campaign retry settings)
* **Independent status tracking** from primary contact
* **Can have unique variables** different from primary

<Tip>
  **Use case example:** A business lead might have the main office number as primary contact, with the decision maker's direct line and mobile as secondary contacts.
</Tip>

## Variables System

Variables personalize AI conversations with lead-specific information. They are inherited from [assistant configuration](/ai-assistants/settings/prompt-and-tools#call-variables) and can be customized per lead.

**Usage in conversations:** Assistant uses variables like `{customer_name}` and `{company}` for personalized responses.

## Key Features

### Lead Management

* **Manual creation** or **CSV/Excel import** with validation
* **Status tracking** through campaign lifecycle
* **Export capabilities** with filtering options

### Campaign Integration

* **Single campaign** assignment per lead
* **Automatic status updates** based on call outcomes
* **Manual status control** for campaign management

### Best Practices

* **Phone format:** International format without spaces (+1234567890)
* **Clean data:** Accurate, current contact information
* **Logical organization:** Prioritize secondary contacts appropriately

<Note>
  For troubleshooting lead management issues, see [Leads Troubleshooting](/troubleshooting/leads).
</Note>

<Note>
  For detailed setup instructions, see [Managing Leads](/leads/managing-leads) and [Importing Leads](/leads/importing-leads).
</Note>


# Managing Leads
Source: https://docs.autocalls.ai/leads/managing-leads

Create, edit, and organize leads with custom variables and secondary contacts

Learn how to create, edit, and manage leads effectively for your campaigns with proper variable setup and secondary contact management.

## Creating a New Lead

### Basic Information

1. **Phone Number:** Enter the primary contact number in international format
2. **Campaign Assignment:** Select which campaign this lead belongs to
3. **Status:** Automatically set to "Created" for new leads

<Note>
  **Phone number format:** Use international format without spaces or parentheses (+1234567890) for automation imports and file uploads.
</Note>

### Variable Setup

#### Assistant Default Variables

When you select a campaign, the lead automatically inherits variables from the [assistant configuration](/ai-assistants/settings/prompt-and-tools#call-variables):

* **Pre-filled values:** Assistant's default variables appear in the form
* **Customization:** Modify values specific to this lead
* **Required fields:** Some variables may be required for campaign functionality

#### Custom Variables

Add personalized information for your AI assistant to use:

**Common variable types:**

* **customer\_name:** Person's name for personalized greetings
* **company:** Business name for B2B conversations
* **last\_interaction:** Previous conversation context
* **preferences:** Customer preferences or requirements
* **budget\_range:** Financial information for sales calls

**Variable format example:**

```json theme={null}
{
  "customer_name": "Sarah Johnson",
  "company": "TechStart Solutions", 
  "last_interaction": "Requested demo of premium features",
  "preferred_contact_time": "Afternoon EST",
  "industry": "Software Development"
}
```

### Secondary Contacts

Add additional phone numbers for the same lead when you have multiple ways to reach them.

#### When to Use Secondary Contacts

* **Decision makers:** Multiple people involved in the decision
* **Backup numbers:** Mobile, office, home numbers for same person
* **Department contacts:** Different departments in same company
* **Time-based contacts:** Different numbers for different times

#### Secondary Contact Setup

1. **Add Secondary Contact:** Click "Add Secondary Contact" in the form
2. **Phone Number:** Enter additional phone number
3. **Variables:** Set specific variables for this contact (optional)
4. **Order:** Contacts are tried in the order you add them

<Tip>
  **Contact order matters:** Campaign will try contacts in sequence. Put the most likely to answer first.
</Tip>

#### Secondary Contact Variables

Each secondary contact can have unique variables:

* **Different person:** Use different name and role variables
* **Same person:** Use same personal info but different contact preferences
* **Department-specific:** Customize for specific department needs

**Example - Multiple decision makers:**

```json theme={null}
// Primary: CEO
{
  "contact_name": "John Smith",
  "role": "CEO", 
  "decision_authority": "Final approval"
}

// Secondary: CTO  
{
  "contact_name": "Jane Doe",
  "role": "CTO",
  "decision_authority": "Technical decisions"
}
```

## Editing Existing Leads

### Modifying Lead Information

* **Phone number:** Update if contact information changes
* **Campaign:** Move lead to different campaign if needed
* **Status:** Manually change status for campaign control

### Variable Management

* **Update values:** Modify existing variable values
* **Add variables:** Include new information for better AI context
* **Remove variables:** Delete outdated or irrelevant data

<Warning>
  **Campaign compatibility:** When changing campaigns, ensure variables match the new assistant's configuration.
</Warning>

### Secondary Contact Management

* **Add contacts:** Include additional phone numbers
* **Remove contacts:** Delete invalid or unnecessary numbers
* **Reorder contacts:** Change calling sequence priority
* **Update variables:** Modify contact-specific information

## Lead Status Management

### Understanding Status Changes

Lead status automatically updates based on campaign activity:

* **Created → Processing:** When campaign starts calling
* **Processing → Completed:** When call succeeds or goal achieved
* **Processing → Rescheduled:** When call needs retry
* **Rescheduled → Max Retries:** When retry limit reached

### Manual Status Control

You can manually change lead status when needed:

#### Reset for Re-calling

**Set to "Created":** Resets lead to be called again

* **Use case:** Lead requested callback at specific time
* **Effect:** Lead rejoins campaign queue
* **Considerations:** Respects campaign retry limits

#### Mark as Complete

**Set to "Completed":** Stops campaign from calling this lead

* **Use case:** Goal achieved through other channels
* **Effect:** Lead excluded from future campaign calls
* **Considerations:** Cannot be automatically reset by campaign

#### Other Status Changes

* **"Scheduled":** Queue for next retry attempt
* **"Max Retries":** Manually mark as exhausted
* **"Rescheduled":** Reset retry timer

<Tip>
  **Status strategy:** Use manual status changes sparingly. Let campaign automation handle most status updates for consistent behavior.
</Tip>

## Bulk Operations

### Bulk Delete

Select multiple leads and delete them:

1. **Filter leads:** Use table filters to select specific leads
2. **Select leads:** Check boxes for leads to delete
3. **Bulk delete:** Choose delete action from bulk actions menu
4. **Confirm:** Review changes before applying

### Bulk Export

Export filtered lead data for external processing:

* **Apply filters:** Filter by campaign, status, date range
* **Select columns:** Choose which data to export
* **Include secondary:** Option to include secondary contacts
* **Download:** CSV format for spreadsheet compatibility

## Lead Organization

Use table filters, sorting, and search to organize leads by campaign, status, date range, or variable content.

## Campaign Integration

* **Single campaign** assignment per lead
* **Variable inheritance** from assistant configuration
* **Automatic coordination** with campaign schedule and retry logic

## Best Practices

### Key Points

* **Phone format:** International format without spaces (+1234567890)
* **Variables:** Use consistent naming and relevant information
* **Secondary contacts:** Order by priority, avoid duplicates
* **Privacy:** Follow data protection requirements

<Note>
  For troubleshooting common lead issues, see [Leads Troubleshooting](/troubleshooting/leads).
</Note>

<Note>
  For information about importing leads in bulk, see [Importing Leads](/leads/importing-leads).
</Note>


# Claude & ChatGPT Connector (MCP)
Source: https://docs.autocalls.ai/mcp-connector

Build and run your AI phone agents straight from Claude or ChatGPT — over a secure, one-time OAuth connection.

The Autocalls connector lets you **build and operate your AI phone agents straight from Claude or
ChatGPT**. Instead of clicking through the dashboard, you just describe what you want — and your AI
assistant does it on your account:

* *"Create an inbound receptionist that books appointments."*
* *"Show me why my last campaign call failed."*
* *"Add three leads to my follow-up campaign and start it."*

<Note>
  It's a **remote MCP server** secured with **OAuth 2.0**. You connect once, sign in to approve, and
  every action stays scoped to **your own Autocalls account** — the connector only ever sees and
  changes your data.
</Note>

## What you can do

<CardGroup>
  <Card title="Build & refine assistants" icon="robot" href="/ai-assistants/what-is-ai-assistant">
    Inbound and outbound: system prompt, voice, language, model and call behaviour. Attach
    knowledgebases (your documents) and mid-call tools (live API lookups during a call).
  </Card>

  <Card title="Run campaigns" icon="bullhorn" href="/campaigns/index">
    Create call, WhatsApp, or SMS campaigns, add leads, set schedule windows, and start or pause them.
  </Card>

  <Card title="Review & improve" icon="magnifying-glass-chart" href="/outbound-calls/overview">
    List calls, read full transcripts and post-call evaluations, then update the assistant or its
    tools — a complete build → review → improve loop.
  </Card>

  <Card title="Manage your account" icon="gear" href="/api-reference/introduction">
    Knowledgebases & documents, phone numbers & SIP trunks, WhatsApp senders & templates,
    conversations, folders, labels, API keys and your blacklist.
  </Card>

  <Card title="Build automations" icon="bolt" href="/automation-platform/introduction">
    Describe what should happen around your calls — follow-ups, spreadsheet logging, callbacks,
    lead intake — and it's built from a ready-made template or from scratch, proven with a real
    test run, and attached to your assistant. Debug failed runs, retry them from the failed step,
    and roll back a change that made things worse.
  </Card>
</CardGroup>

Read and write are separate tools. Actions that **spend balance** (placing a call, sending
SMS/WhatsApp, buying a number) or **delete data** always ask for confirmation first. Integration
secrets (e.g. auth tokens on your mid-call tools) are **masked** in responses.

## Before you start

* An **Autocalls account** at [app.autocalls.ai](https://app.autocalls.ai) — or your white-label
  provider's domain.
* An **active plan** for the features you use (some actions consume call minutes or chat credits).

### Your connection link

This is the secure address Claude and ChatGPT use to reach your account. Copy it — you'll paste it
during setup, then sign in to approve.

```
https://app.autocalls.ai/mcp
```

<Info>
  **White-label customers:** use **your provider's domain** instead — `https://{your-domain}/mcp`.
  The branding follows the domain, so you only ever see your provider's brand.
</Info>

## Add the connector

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="Open Customize">
        In Claude, open the left sidebar and click **Customize**.

        <Frame>
          <img alt="Open the Customize panel in Claude" />
        </Frame>
      </Step>

      <Step title="Open Connectors">
        In the settings panel that opens, click **Connectors** in the left sidebar.

        <Frame>
          <img alt="Open Connectors in the Claude settings panel" />
        </Frame>
      </Step>

      <Step title="Add a custom connector">
        Click **Add** in the top-right of the Connectors panel, then choose **Add custom connector**.

        <Frame>
          <img alt="Add a custom connector in Claude" />
        </Frame>
      </Step>

      <Step title="Name it and paste your link">
        Type any name (e.g. *Autocalls*), paste your connection link into **Remote MCP server URL**,
        leave the OAuth fields empty, then click **Add**.

        <Frame>
          <img alt="Paste the Autocalls MCP URL in Claude" />
        </Frame>
      </Step>

      <Step title="Sign in and approve">
        Log in to your Autocalls account and approve. Your tools then appear in the list — you're
        connected.

        <Frame>
          <img alt="Sign in and approve the Autocalls connector in Claude" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="ChatGPT">
    <Note>
      **Recommended: use the ChatGPT desktop app**, not the free web version. Custom connectors work
      poorly on the free web version — tools may not load into your chat, and actions that place a
      real phone call are blocked by OpenAI's safety layer in the browser (see the FAQ below).
    </Note>

    <Steps>
      <Step title="Open Settings">
        In ChatGPT, click your name at the bottom-left, then **Settings**.

        <Frame>
          <img alt="Open Settings in ChatGPT" />
        </Frame>
      </Step>

      <Step title="Turn on Developer mode">
        Open **Security and login**, scroll down, and switch on **Developer mode**. It shows an
        "Elevated risk" note — that's expected for custom connectors.

        <Frame>
          <img alt="Enable Developer mode under Security and login in ChatGPT" />
        </Frame>
      </Step>

      <Step title="Open Plugins">
        Back in ChatGPT, click **Plugins** in the left sidebar.

        <Frame>
          <img alt="Open Plugins in the ChatGPT sidebar" />
        </Frame>
      </Step>

      <Step title="Click the + button">
        It's in the top-right of the Plugins page, next to the search bar.

        <Frame>
          <img alt="Click the plus button on the Plugins page in ChatGPT" />
        </Frame>
      </Step>

      <Step title="Paste your link and create">
        Give it a name, paste your connection link into the **Server URL** field, set
        **Authentication** to **OAuth**, tick *"I understand and want to continue"*, then **Create**.
        Sign in to your Autocalls account and approve.

        <Frame>
          <img alt="Paste the Autocalls MCP URL and create the app in ChatGPT" />
        </Frame>
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Tip>
  Once the connector is listed in the Claude and ChatGPT directories, you'll also be able to add it in
  one click by searching for **Autocalls** under Settings → Connectors — no manual URL needed.
</Tip>

## Try it

Start a new chat in Claude or ChatGPT and ask, for example:

<CardGroup>
  <Card title="Build" icon="wand-magic-sparkles">
    "Create an inbound receptionist for my dental clinic that books appointments and answers FAQs."
  </Card>

  <Card title="Improve" icon="arrow-trend-up">
    "Read my last 5 calls and tell me what my assistant got wrong."
  </Card>

  <Card title="Integrate" icon="plug-circle-bolt">
    "Create a mid-call tool that looks up an order by number from our API."
  </Card>

  <Card title="Run" icon="bullhorn">
    "Set up an outbound campaign for this week's leads and start it."
  </Card>

  <Card title="Automate" icon="bolt">
    "After every call, save qualified leads to my Google Sheet and email me when a caller asks for
    a callback."
  </Card>
</CardGroup>

## Security & privacy

* **OAuth 2.0** with a branded consent screen — no API key is ever pasted into the chat client.
* **Scoped to your account** — the connector can only see and change your own data.
* **Secrets masked** — auth tokens stored on your tools are never returned in plain text.
* **No chat-history harvesting** — the connector acts only on your Autocalls resources.
* Privacy policy: [autocalls.ai/privacy-policy](https://autocalls.ai/privacy-policy).

## FAQ

<AccordionGroup>
  <Accordion title="Which AI apps can I use it with?">
    This guide covers **Claude** and **ChatGPT**. The connector is a standard remote MCP server, so it
    also works with any other MCP-compatible client (for example Cursor or VS Code) — the setup is the
    same: add a custom connector and paste your connection link.
  </Accordion>

  <Accordion title="Do I need an API key?">
    No. Connection is handled by **OAuth** — you simply sign in to your Autocalls account and approve.
    No key is pasted into the chat app.
  </Accordion>

  <Accordion title="Is it safe to connect?">
    Yes. Every tool is scoped to your own authenticated account, write and destructive actions ask for
    confirmation, and any integration secrets you've stored are masked in responses.
  </Accordion>

  <Accordion title="Will it spend my balance?">
    Only when you explicitly ask it to place a call or send an SMS/WhatsApp — and it confirms first.
    Building and editing assistants, reading calls, and managing your account don't place calls.
  </Accordion>

  <Accordion title={`My call is blocked in ChatGPT ("blocked by OpenAI safety checks")`}>
    This block comes from **OpenAI's own safety layer inside ChatGPT**, not from us. When ChatGPT is
    about to trigger a tool that places a real outbound phone call, OpenAI's policy on AI agents
    initiating phone calls stops it before the request ever reaches us. We can't override OpenAI's
    decision from our side, and it mainly affects the **ChatGPT browser**.

    Things that work:

    * **ChatGPT desktop app** or an **OpenAI agent** — the same call goes through there.
    * **Claude** — the call works there too, including placing a reminder call through the assistant.
    * **Schedule an outbound campaign** — for reminder calls ("call John at 16:00"), set up a
      scheduled outbound campaign (assistant + contact + time) from the dashboard or via the API /
      Automate. It never goes through ChatGPT's safety layer, so it's never blocked.

    A native ChatGPT integration is in review with OpenAI and coming soon.
  </Accordion>
</AccordionGroup>

## Support

Questions? Email [contact@autocalls.ai](mailto:contact@autocalls.ai) or browse the rest of the
[documentation](/introduction/what-is-autocalls).


# Caller ID & Handling
Source: https://docs.autocalls.ai/outbound-calls/caller-id

Learn how to configure and manage caller ID for outbound campaigns

When you launch an outbound campaign, you can choose which number appears on recipients' phones.

## 1. Dedicated Number

* If you've rented a local or toll-free number, you can select it as the "Phone number" in the [assistant settings](/ai-assistants/settings/general#phone-number-configuration).
* Good for brand consistency or if you also accept inbound calls on the same line.
* **No OTP verification needed** for numbers rented through Autocalls.ai.

## 2. Verified Existing Number (Caller ID Only)

* If you want your personal or company phone line to appear, verify it with an **OTP** or short call.
* This won't handle inbound calls for the AI, but the lead sees that recognized number on caller ID.
* **Note**: OTP verification is ONLY required when using your own existing number as Caller ID.

## 3. SIP Integration

* If you use a PBX or VOIP platform, you might pass a custom caller ID from your existing system.
* Make sure your trunk or provider is set to allow a specific outbound Caller ID.

## 4. Country-Specific Rules

* Some regions prevent using numbers you don't own as Caller ID.
* Always ensure you have the right to present that number to avoid spam or legal issues.

***

**Tip:** Test by calling your own phone or a friendly colleague to confirm the correct caller ID is displayed before launching a big campaign.


# Creating & Managing Campaigns
Source: https://docs.autocalls.ai/outbound-calls/campaigns

Step-by-step guide to creating and managing outbound call campaigns, including lead imports and monitoring

An outbound "campaign" determines when, how, and to whom calls are made. Campaigns automate calls to multiple leads using your AI assistant with intelligent scheduling and retry logic.

## Quick Setup

1. **Go to Outbound / Campaigns** in your dashboard
2. **Click "Create New Campaign"**:
   * **Name**: e.g. "January Promo," "Payment Reminder," etc.
   * **Assistant**: which AI assistant will handle these calls?
   * **Schedule**: choose time windows and allowed days

## Lead Import Options

* **CSV File**: Upload phone numbers (plus any extra columns, like name or account number)
* **Google Sheets**: Connect via the no-code platform or direct integration to pull leads
* **CRM Integration**: HubSpot, GoHighLevel, etc. can send leads directly via API or automation

## Key Settings

**Call Retries & Scheduling:**

* **Max Retries**: e.g., attempt each lead up to 2 times if they don't answer
* **Retry Interval**: minutes/hours between retries
* **Time Window**: e.g., only call between 9 AM and 6 PM local time to avoid inconveniencing leads

**Monitoring & Control:**

* Once live, calls happen automatically during allowed hours
* You can **pause** or **stop** the campaign anytime to revise your script or leads list
* **Campaign Reports** show call results, answer rates, and duration analytics

## Best Practices

* **Conservative scheduling**: Business hours, respect time zones
* **Start with 2-3 retries**: Monitor and adjust based on feedback
* **Clean lead data**: Valid numbers, remove duplicates
* **Monitor costs**: Large campaigns can run thousands of parallel calls

<Note>
  **Large campaigns** with thousands of leads can run concurrently, as AI can handle parallel calls. Watch your minute usage to avoid unexpected costs.
</Note>

***

For comprehensive setup instructions, advanced features, lead management, status tracking, and troubleshooting, see the complete [Campaigns Documentation](/campaigns/index).


# Mass/Parallel Dialing
Source: https://docs.autocalls.ai/outbound-calls/mass-dialing

Learn how to manage high-volume outbound campaigns with parallel dialing while maintaining compliance

One advantage of AI-driven outbound is that you can dial large batches of leads simultaneously without hiring more human agents.

## 1. Handling High-Volume Campaigns

* **Upload Thousands of Contacts**:
  * If your plan or usage limit allows, you can import big lists from CSV or integrate with your CRM.
* **Parallel Calls**:
  * A single phone number can handle multiple concurrent calls, but watch for compliance (some regions have rules against excessive cold calls).

## 2. Preventing Spam Flags

* **Reasonable Call Pace**:
  * Don't launch 10,000 calls instantly. Stagger them with short intervals to avoid spam detection or network blocks.
* **Caller ID Rotation** (Optional):
  * Some advanced users rotate caller IDs, but ensure they're all verified and within legal guidelines.

## 3. Real-Time Monitoring

* **Dashboard**:
  * See how many calls are active, success/no-answer rates, average call durations, etc.
* **Campaign Pause**:
  * If you spot unusual patterns (like high "no answer" or negative responses), pause the campaign to refine your script or lead quality.

***

**Note:** High-volume dialing may ramp up your minute usage quickly. Keep an eye on [Costs & Pricing](/pricing/overview) to avoid surprises.


# Outbound Calls Overview
Source: https://docs.autocalls.ai/outbound-calls/overview

Learn about outbound call campaigns, including sales calls, reminders, and follow-ups using AI assistants

Autocalls.ai supports outbound call campaigns where the AI calls leads or customers automatically. Ideal for:

* **Sales/Marketing**: Reaching out to potential clients, offering promotions.
* **Collections/Reminders**: Checking overdue payments or reminding appointments.
* **Customer Follow-Ups**: Post-purchase check-ins, feedback surveys, etc.

## Key Elements

1. **Leads List**\
   Usually a list of phone numbers (with optional data like names or IDs).

2. **Campaign**\
   A structured way to manage who gets called, how many times, and in which time window.

3. **AI Assistant**\
   Handles the conversation, guided by your system prompt and call script.

4. **Caller ID**\
   The number shown on recipients' phones. Could be a dedicated number or your verified existing line.

***

**Tip:** Each campaign references an AI assistant. If your script changes drastically, you might create a new assistant or edit the existing one.


# Scripts & Prompts for Sales or Collections
Source: https://docs.autocalls.ai/outbound-calls/scripts-and-prompts

Learn how to write effective system prompts and scripts for outbound sales and collection calls

The power of outbound calling lies in having a clear, well-structured conversation flow. Here's how to craft an effective script.

## 1. System Prompt Best Practices

* **Introduce Your Company**: *"You are the Sales Bot for Ace Marketing…"*
* **Purpose**: *"…you offer a 20% discount if the user is interested, or schedule a callback if uncertain."*
* **Objection Handling**: *"…if they say 'no budget', attempt to collect a reason or set a reminder for next month."*

## 2. Example (Sales Prompt)

```plaintext theme={null}
"You are the Sales Bot for ACME Corp. Greet politely, mention the new product launch, and offer a 10% discount if the lead is interested. If they ask for more info, invite them to schedule a call with a human agent. If they refuse or express disinterest, politely end the call."
```

## 3. Example (Collections Prompt)

```plaintext theme={null}
"You are the Collections Bot for ABC Finance. Greet the user, verify their name and last payment date. If they confirm a willingness to pay, gather payment details or schedule a callback. If they refuse, politely note the reason and end the call."
```

## 4. Handling Yes/No/Maybe

* **Yes**: Provide details or transfer to a human for finalizing.
* **No**: Respectfully close, mark lead as not interested.
* **Maybe**: Offer to schedule a follow-up call or provide more info.

***

**Tip:** Keep your script short and direct. The AI can adapt, but a concise prompt helps keep calls focused and efficient.


# Voicemail Handling
Source: https://docs.autocalls.ai/outbound-calls/voicemail-handling

Learn how your AI assistant handles voicemail detection in outbound calls

When making outbound calls, the AI assistant can automatically detect if it has reached a voicemail or answering machine:

## Voicemail Detection

* The AI uses advanced detection to identify voicemail systems
* When voicemail is detected, the call is automatically ended
* This helps avoid wasting resources and ensures efficient call handling

## Benefits of Auto-Drop

* Saves time and call minutes
* Prevents awkward or incomplete interactions
* Allows for automatic retry scheduling
* Maintains professional communication standards

## Best Practices

* Monitor call logs to track voicemail rates
* Consider time zones when scheduling calls
* Plan retries during different hours
* Target business hours when people are more likely to answer

## Reporting

You can track voicemail detection in your campaign analytics:

* Number of detected voicemails
* Time of day patterns
* Success rates for different calling times

***

**Tip:** If you're getting too many voicemails, try adjusting your campaign's calling hours to when people are more likely to answer.


# Assigning Numbers to Assistants
Source: https://docs.autocalls.ai/phone-numbers/assigning-to-assistants

Learn how to connect your phone numbers to AI assistants for both inbound and outbound calls

After you've acquired a number (or configured SIP or Caller ID), you'll need to assign it to your AI assistant. The process is the same whether you're using the number for inbound or outbound calls.

## Assigning a Number

1. Go to **Assistants** → **(Your Assistant)** → **[Settings](/ai-assistants/settings/general#phone-number-configuration)**
2. Under **Phone Numbers**, select a number from your Autocalls.ai inventory
3. Click **Save** to apply the changes

## Number Usage

Once assigned, the number can be used for:

* **Inbound**: Callers dialing this number will reach your AI assistant
* **Outbound**: The number will appear as Caller ID for outbound campaigns
* **Both**: The same number can handle both inbound and outbound calls

## Number Verification

For numbers not rented from Autocalls.ai:

* You'll need to verify ownership via **OTP code** or a **verification call**
* Once verified, the number can be used for both inbound and outbound
* Verification status persists across different assistants

## Testing

Before going live:

1. Make an inbound test call to verify the assistant answers
2. Run a test outbound call to check Caller ID display
3. Verify any specific features (call transfers, voicemail, etc.)

***

**Tip:** Always test both inbound and outbound functionality after making any changes to number assignments.


# Pricing & Regions
Source: https://docs.autocalls.ai/phone-numbers/pricing-and-regions

Understand phone number pricing across different regions, documentation requirements, and additional fees

Phone number rental fees vary based on country, number type, and local telecom rules. Below is a general guide:

## 1. Typical Monthly Costs

* **US/Canada**: Around \$3.99/month.
* **UK**: Typically \~£3/month, but can vary.
* **EU Countries**: €3–€5/month, or more for toll-free lines.
* **Others**: Some countries can be \$3 or more, depending on local taxes.

## 2. Advanced Documentation

* **Business Registration**: Many countries (e.g., France, Germany, Italy) require a local address or company registration to rent a number.
* **ID Proof**: Some carriers need a government-issued ID for individuals.

## 3. Additional Fees

* Some toll-free lines or special region numbers have higher monthly costs or per-minute surcharges.
* Calls to or from certain regions might also incur higher usage rates—see [Costs & Pricing](/pricing/overview) for full details.

## 4. Don't See Your Region?

* Contact us through the chat widget in the bottom right corner of the screen inside the app to request a number.
* Provide the necessary documentation, and we'll attempt to source a local number through our carrier partners.

***

**Note:** If you're integrating **SIP** or using **Caller ID** verification, you do not pay a monthly rental, but usage costs may still apply.


# Purchasing & Managing Numbers
Source: https://docs.autocalls.ai/phone-numbers/purchasing-and-managing

Learn how to purchase, provision, and manage phone numbers for your AI assistants

## Getting Started

1. If you see a number you want in the platform, rent it instantly.
2. If it's not listed, contact us for custom provisioning. We'll let you know which documents are required.
3. Pricing may differ by country, we'll provide final monthly cost once the number is ready.
4. Any type of number (local, national, or toll-free) can be custom-provisioned if not visible in the platform.

## Custom Provisioning

* Our team handles the entire process with the carrier.
* We'll request any required documents based on the country's regulations.
* Typical processing time is 1-3 business days.

## After Purchase

* Assign the number to an AI assistant for inbound calls.
* Use it as Caller ID for outbound campaigns if desired.
* Monitor usage and costs in your dashboard.

***

**Tip:** Remember to **assign the purchased number** to an AI assistant.


# SMS Capabilities
Source: https://docs.autocalls.ai/phone-numbers/sms-capabilities

Learn about SMS features, requirements, and pricing for your phone numbers

<Card title="Detailed SMS Documentation" icon="book-open" href="/automation-platform/calls-related/sms-capabilities">
  This is an overview of SMS features. For detailed instructions on sending SMS
  through automation flows, check our [Automation Platform
  Documentation](/automation-platform/calls-related/sms-capabilities).
</Card>

## Requirements

To send SMS messages, you need:

* An SMS-capable phone number
* Sufficient credits in your account
* Proper automation flow setup

## SMS Segments

SMS messages are split into segments:

* Each segment is 160 characters for standard ASCII text
* Or 70 characters for Unicode (special characters, emojis)
* Longer messages are automatically split into multiple segments
* You are charged per segment sent

For example:

* "Hello! How are you?" (16 chars) = 1 segment
* A message with 200 ASCII chars = 2 segments
* A message with emojis and 100 chars = 2 segments

## Costs

SMS pricing varies by:

* Destination country
* Number of segments
* Type of content (standard/unicode)

## Monitoring & History

Track your SMS activity in the dashboard:

* Delivery status
* Timestamp
* Number of segments
* Cost per message
* Recipient details
* Content preview

## Best Practices

1. **Message Length**

   * Keep messages concise
   * Monitor segment count
   * Use standard characters when possible

2. **Compliance**

   * Include opt-out instructions
   * Follow local regulations
   * Respect quiet hours

3. **Testing**
   * Verify number capabilities
   * Test delivery to different carriers
   * Monitor delivery rates

***

**Want to start sending SMS?** Check out our [automation platform documentation](/automation-platform/calls-related/sms-capabilities) to learn how to set up SMS workflows.


# Types of Phone Numbers
Source: https://docs.autocalls.ai/phone-numbers/types

Learn about the different types of phone numbers you can use with Autocalls.ai: dedicated numbers, SIP integration, and Caller ID

Autocalls.ai lets you connect three different kinds of phone numbers to your AI assistant:

1. **Normal (Dedicated) Numbers**

   * Rented directly from Autocalls.ai.
   * Can be used for **both inbound** and **outbound** calls.
   * Typically charged as a monthly rental, with the ability to handle multiple parallel calls on a single number.

2. **SIP Integration (VOIP/PBX)**

   * Connect an existing VOIP or PBX number via SIP.
   * This setup allows you to keep your existing numbers while benefiting from Autocalls.ai's AI.
   * Works for **both inbound and outbound**—see our [SIP Integration Guide](/provisioning/sip-trunking/sip-integration) for setup instructions.
   * You can configure this directly in your dashboard under Phone Numbers.

3. **Caller ID (Outbound Only)**
   * When you already have a phone number (e.g., your personal or business line) but don't want to port it or integrate via SIP.
   * You verify ownership (via OTP or a short call) so that number can appear on people's caller ID.
   * **Inbound calls won't be answered by the AI** if you use Caller ID alone—it only masks the AI's outbound calls.

## Choosing the Right Option

* If you need **inbound** and you don't already have a VOIP solution, consider renting a dedicated number.
* If you have an established **PBX** or VOIP provider, use **SIP integration**.
* If you just want to do **outbound** calls showing your existing phone line, pick **Caller ID**.


# Number Rentals & International Rates
Source: https://docs.autocalls.ai/pricing/number-rentals

Understand phone number rental costs, plus how SIP and Caller ID usage is billed by the minute.

Autocalls.ai offers multiple ways to handle phone numbers for inbound or outbound calls. You can **rent** a dedicated number from us, use a **SIP** trunk (no monthly fee but carrier costs are on your own PBX), or verify an **existing Caller ID** (also no monthly fee, but region-based per-minute charges).

***

## 1. Renting a Dedicated Number

If you want a fully managed inbound/outbound line, you can rent it directly in the platform:

* **Monthly Fee**: Typically \$3.99/month for standard local numbers (US/CA/UK). Regions vary:
  * **EU Countries**: €3–€5/month
  * **Latin America, Asia, Africa**: \$10+ in some cases, depending on availability or local taxes
* **Custom Provisioning**: If you don't see your desired country or region listed, our team can custom-provision a number after verifying local documents.

**Per-Minute Rates**

* Outbound calls on a rented number: depends on the country you're calling—could range from \$0.05/min to \$0.50/min if it's an expensive destination.
* Inbound calls: usually no extra charge unless it's a special/toll scenario in that region.

***

## 2. SIP Integration (No Monthly Fee)

If you already have a VOIP/PBX solution, you can integrate via a **SIP trunk** with **no monthly rental** from Autocalls.ai. Instead, you pay:

* **SIP Per-Minute**: \$0.00045/min on our side for carrier bridging. Your VOIP provider may also have separate usage fees.
* **Your Existing Number**: You'll continue to use your own phone lines for inbound and outbound, but the carrier layer costs \$0.00045/min with us whenever the AI is on the call.

This is ideal if you're comfortable managing your own phone system or want to keep your existing numbers without renting from us. See our [SIP Integration Guide](/provisioning/sip-trunking/sip-integration) for setup instructions.

***

## 3. Caller ID (No Monthly Fee)

You can verify an existing number for **outbound calls** only—no inbound routing.

* **Verification**: We confirm ownership via a short OTP or call.
* **Per-Minute**: For the telephony used behind the scenes, we charge region-based rates.
  * **Example**: In the US, Caller ID usage might be \$0.01/min.
  * Other countries vary; contact support for specifics.

> **Note**: Caller ID alone does **not** enable inbound AI; it only masks your outbound calls with your verified number.

***

## 4. International Rates & Regions

When making outbound calls:

* **Carrier Rates**: Some countries cost \$0.01/min, others \$0.50/min due to local carriers.
* **Inbound**: If you rent a number in a high-cost region or special type, inbound calls could have surcharges.

Regardless of whether you rent a number or use Caller ID/SIP, the **carrier portion** of the call cost depends on the destination/origin country and is typically added to your overall usage.

***

## 5. Putting It All Together

1. **Rent a Number**
   * Pay a monthly fee (from \$3.99), plus standard inbound/outbound carrier costs for calls on that line.
2. **Use SIP**
   * No monthly from us, but a \$0.00045/min AI bridging cost, plus your own PBX fees.
3. **Caller ID**
   * No monthly from us, but region-based per-minute telephony charges (e.g., \$0.01/min in the US). Outbound only.


# Cost Overview
Source: https://docs.autocalls.ai/pricing/overview

Understand the main components of Autocalls.ai pricing, including call minutes, number rentals, and optional fees

Autocalls.ai uses a **credit/minute system** to track usage for both AI processing and carrier network fees. Here's how it breaks down:

***

## 1. Main Components

1. **AI Cost**

   * **Minimum charge of 30 seconds (0.5 min)** per call. Any call under 30 seconds is billed as 30 seconds — e.g., a 10-second call deducts 0.5 min from your balance.
   * Beyond 30 seconds, billing is **per second**. For example, a 35-second call deducts exactly 35 seconds (\~0.58 min) from your balance.
   * Rate depends on your plan (Starter, Pro, Agency, etc.).

2. **Carrier Cost**

   * The telecom side of the call, generally **rounded up** to the next minute and converted to your plan’s minute rate.
   * Region-dependent: e.g., calling US vs. Europe vs. Asia has different carrier rates.

3. **Number Rental**

   * If you rent a phone number, there’s a monthly fee (e.g., \$3.99 for a standard US number).
   * If your region isn’t listed, we can custom-provision a number upon verifying documents.
   * Each number’s cost is billed monthly until released.

4. **Extra Fees (Optional)**
   * **SMS**: If your number is SMS-capable, standard per-message fees apply.
   * **Voicemail detection**: Billed as 1 minute per call.
   * **High-Volume**: Potential bulk discounts if you exceed tens of thousands of minutes monthly.

***

## 2. Visual Example

Suppose you have 200 included minutes in your plan. A typical 1-minute call might consume \~1.5 minutes from your balance if carrier cost is half your plan’s rate. This means you’d have about 198.5 left. By the end of the billing cycle, any unused minutes do no rollover.

***

## 3. Checking Call Logs

* **Dashboard → Call History**: See each call’s final cost breakdown.
  * AI usage (seconds → fraction of a minute).
  * Carrier usage (rounded up → fraction of a minute after conversion).
  * Summed total in “minutes” deducted from your included or purchased balance.

***

## 4. Monitoring & Alerts

* Watch your real-time usage in the **dashboard**.

***

## 5. Putting It All Together

1. **Pick a Plan**: Decide on Starter, Pro, or Agency—higher plans have cheaper AI rates.
2. **Acquire or Verify a Number**: Rent from Autocalls.ai or add your own as caller ID for outbound.
3. **Start Making Calls**: Inbound or outbound usage deducts from your minute balance.
4. **SMS & Extras**: If relevant, each text or advanced feature also deducts from your balance or is billed separately.

That’s the overall cost structure. For a deeper look at the math behind minute conversion, check our [Pricing Breakdown](/pricing/usage-based) page.


# Pricing Breakdown
Source: https://docs.autocalls.ai/pricing/usage-based

Detailed explanation of how call minutes are calculated and billed

# Pricing Breakdown

Autocalls.ai uses a **minutes-based** system for billing. These minutes (or tokens/credits) get **deducted** from your balance each time you make or receive a call. The actual “per-minute cost” depends on your plan, and **carrier costs** are also converted into minutes. Below is how it works.

***

## 1. Inbound vs. Outbound Calls

* **Inbound**: You spend minutes as soon as the AI assistant picks up and is engaged in a call.
* **Outbound**: Minutes start deducting once the customer answers the call and stays connected. Dial time is not billed.

> **Note**: A call is considered active until the AI or the user hangs up, **or** until voicemail detection ends the call if the user’s voicemail answers (for outbound).

***

## 2. How Minutes Are Used

### a) AI Spoken Time

* There is a **minimum charge of 30 seconds (0.5 min)** per call. Any call shorter than 30 seconds is still billed as 30 seconds.
* Beyond 30 seconds, the cost is **prorated by the second**. For example, a 45-second call uses 0.75 minutes from your plan.

### b) Carrier Conversion

* **Carrier cost** (the telecom network fee) is also deducted from your balance **but** is typically **rounded up** to the next minute.
* We convert the carrier’s dollar amount to minutes at your plan’s rate.
  * **Example**: If your carrier charge is \$0.05 for a 1-minute call, and your plan’s AI rate is \$0.10/min, we convert that \$0.05 to 0.5 minutes from your balance.

**So a single 1-minute conversation might consume:**

* **1 AI minute** (for the assistant)
* **+ 0.5 “carrier minutes”** (converted from the carrier’s \$0.05 to half your AI cost).
* **= 1.5 minutes total** deducted from your plan balance.

***

## 3. Minimum Charge & Per-Second Billing vs. Rounding

1. **AI Time**

   * **Minimum charge of 30 seconds** (0.5 min). Calls under 30 seconds are billed as 30 seconds.
   * Beyond 30 seconds, **measured per second** — so 70 seconds is \~1.17 minutes of AI usage.
   * Deducted exactly from your plan’s minute balance.

2. **Carrier Time**
   * **Rounded to next full minute** for the network fee.
   * Then converted into a fraction of your AI plan cost to decide how many “minutes” to deduct from your credit balance.

***

## 4. Included Minutes & Top-Ups

* **Each Plan**: Usually includes a monthly allotment of minutes.
* **Using Up Minutes**: Once you exceed included minutes, you can **top up** your wallet with additional minutes at your plan’s rate.
* **No Rollover**: Unused minutes typically don’t roll over to the next month.

**Example**

> You’re on the **Starter Plan** with 200 included minutes:
>
> * If you make enough calls that total 180 AI minutes + carrier conversions = 180 used, you have 20 left this month.
> * Next month, you reset to 200. If you need 210 minutes, you pay for 10 extra minutes at your plan’s rate.

***

## 5. Volume Discounts or Tiers

* Plans vary (e.g., **Starter** at \$0.20/min, **Pro** at \$0.15/min, **Agency** at \$0.09/min).
* High-volume usage (like 50,000+ minutes/month) can often get **bulk discounts** by contacting sales.

***

## 6. Quick Usage Examples

### Example A (Outbound Call, Starter Plan)

* **AI Rate**: \$0.20/min
* **Call Duration**: 30 seconds → 0.5 AI minutes = \$0.10 AI cost.
* **Carrier**: \$0.01/min, but 30 seconds → 1 minute rounded up → \$0.01.
  * \$0.01 at your plan’s \$0.20 rate = 0.05 “plan minutes” used (Or if you do a simpler approach, \$0.01 / \$0.20 = 0.05 minutes)
* **Total**: 0.5 (AI) + 0.05 (carrier) = 0.55 minutes from your plan. If you had 200 included, you’d have 199.45 left.

### Example B (Inbound Call, Pro Plan)

* **AI Rate**: \$0.15/min
* **Call Duration**: 90 seconds → 1.5 AI minutes = \$0.225 AI cost.
* **Carrier**: Suppose inbound is \$0.015/min, rounding up to 2 minutes if the call was 1.5 min. That’s \$0.03 total.
  * \$0.03 / \$0.15 = 0.2 minutes from your plan.
* **Total**: 1.5 (AI) + 0.2 (carrier) = 1.7 minutes deducted.

***

### FAQ

* **Do I pay double if user + AI talk simultaneously?**\
  **No**, it’s based on total call duration, not per speaker concurrency.
* **What if someone picks up then instantly hangs up?**\
  The minimum AI charge is 30 seconds (0.5 min), even if the call lasted only a few seconds. The carrier portion may also round up to 1 minute.

***

**Bottom Line**\
All calls burn **AI time** plus a **converted carrier cost** from your plan’s minute balance. Keep track of usage in your dashboard, top up if needed, and choose the plan that best suits your volume.


# Managing Your Numbers
Source: https://docs.autocalls.ai/provisioning/managing-numbers

Learn how to view, label, release, and manage your provisioned phone numbers

After you meet any compliance requirements and purchase or provision your numbers:

1. **View All Numbers**

   * In your dashboard → **Numbers**. You'll see monthly costs, expiration/renewal dates, etc.

2. **Releasing or Renewing**

   * Release a number if you no longer need it.
   * Renewals happen automatically each month unless you release it.

3. **Scaling Up**
   * If you need multiple lines for different markets, repeat the provisioning steps.


# Phone System Integrations
Source: https://docs.autocalls.ai/provisioning/phone-system-integrations

Learn how to integrate Autocalls.ai with your existing PBX or VOIP infrastructure through SIP trunks

For businesses with existing PBX or VOIP infrastructure, Autocalls.ai can integrate through SIP trunks or direct connections:

## 1. SIP Trunk

* **How It Works**: You share your SIP credentials (server, username, password). Autocalls.ai configures a trunk internally.
* **Inbound/Outbound**: AI can pick up inbound calls from your PBX or place outbound calls using your existing number ranges.

## 2. Caller ID Forwarding

* If your PBX already handles call routing, pass the call to Autocalls.ai only when certain conditions are met (like after IVR selection).

## 3. Hybrid Model

* Some advanced setups keep human agents on your PBX but leverage the AI for high-volume or after-hours calls.
* Example: *During business hours, normal agents handle calls. After hours, calls route to the AI assistant via SIP trunk.*

## 4. Things to Note

* SIP sometimes requires opening firewall ports or whitelisting IPs.
* Carrier charges from your PBX provider still apply, plus any Autocalls.ai usage fees.

***

**Tip:** Contact support for guidance if you're new to SIP or PBX integration. We can assist with the config steps.


# DIDLogic Integration
Source: https://docs.autocalls.ai/provisioning/sip-trunking/didlogic

A step by step guide to connect your DIDLogic account via SIP trunking

<Steps>
  <Step title="Purchase a Phone Number">
    Log in to your DIDLogic dashboard at [app.didlogic.com](https://app.didlogic.com) and go to the **BUY** tab. Search by country and area code, add a number to your cart, and complete checkout. Your new number will appear under the **PURCHASED** tab.

    <Frame>
      <img alt="DIDLogic BUY tab with country search" />
    </Frame>
  </Step>

  <Step title="Configure Your SIP Account (Outbound)">
    Go to the **SIP** tab and click **Edit** on your SIP account.

    <Frame>
      <img alt="DIDLogic SIP tab showing accounts list" />
    </Frame>

    <Frame>
      <img alt="DIDLogic Edit SIP account" />
    </Frame>

    Note the **SIP account number** (e.g., `12345`) — this is your **username** that you will use in Autocalls. Set a password in both the **Password** and **Confirm Password** fields — you will use this same password when importing the number to Autocalls.

    <Frame>
      <img alt="DIDLogic SIP password fields" />
    </Frame>

    Enable **"Restrict to authorized IPs"** and add the IP address `34.195.177.252`, then click **Add** and **Update**.

    <Frame>
      <img alt="DIDLogic Restrict to authorized IPs with 34.195.177.252 added" />
    </Frame>

    Scroll down to find your region and copy the **SIP URI** from the regional gateway list. You will need this for the outbound settings in Autocalls.

    <Frame>
      <img alt="DIDLogic regional SIP URI selection" />
    </Frame>
  </Step>

  <Step title="Configure Inbound Routing (in DIDLogic)">
    Go to the **PURCHASED** tab and click **Destination** next to your phone number.

    <Frame>
      <img alt="DIDLogic Purchased numbers list" />
    </Frame>

    Delete any existing destination, then change the selector from "SIP device" to **"SIP URI"**.

    <Frame>
      <img alt="DIDLogic selecting SIP URI type" />
    </Frame>

    Enter the SIP URI in the following format:

    ```
    <number_without_plus>@5wed79aeavr.sip.livekit.cloud
    ```

    For example, if your number is `+15551234567`, enter:

    ```
    15551234567@5wed79aeavr.sip.livekit.cloud
    ```

    Click **Add**.
  </Step>

  <Step title="Import Number to Autocalls">
    Go to your Autocalls dashboard → **Your Phone Numbers** → **"Integrate SIP trunk"** and fill in your details:

    ```
    Phone number: Your DIDLogic number in E.164 format (e.g., +15551234567)
    Username: The SIP account number from Step 2 (e.g., 12345)
    Password: The password you set in Step 2
    ```

    <Frame>
      <img alt="Fill in SIP integration details" />
    </Frame>

    Under **Outbound settings**, paste the regional SIP URI you copied in Step 2. Set **Number format** to **"International with + in front"** and enable **"Outbound call will come from a fixed IP address"**.

    <Frame>
      <img alt="Outbound SIP settings" />
    </Frame>

    Under **Inbound settings**, select **"IP Address"** as the authorization type. Add the IP address of your chosen DIDLogic regional gateway from the table below:

    | Gateway              | IP Address      |
    | -------------------- | --------------- |
    | sip.nl.didlogic.net  | 89.149.192.7    |
    | sip.uk.didlogic.net  | 23.19.63.1      |
    | sip.se.didlogic.net  | 5.150.254.205   |
    | sip.de.didlogic.net  | 157.230.96.24   |
    | sip.fr.didlogic.net  | 159.8.84.235    |
    | sip.hk.didlogic.net  | 188.42.84.76    |
    | sip.sg.didlogic.net  | 188.42.84.76    |
    | sip.au.didlogic.net  | 119.9.12.222    |
    | sip.nz.didlogic.net  | 131.203.181.17  |
    | sip.ir.didlogic.net  | 161.202.135.82  |
    | sip.ca.didlogic.net  | 138.197.143.154 |
    | sip.lax.didlogic.net | 185.118.62.77   |
    | sip.nyc.didlogic.net | 192.241.183.87  |
    | sip.za.didlogic.net  | 102.130.116.205 |
    | sip.br.didlogic.net  | 169.57.132.146  |

    <Frame>
      <img alt="Inbound SIP settings" />
    </Frame>

    Select the **Country** where your SIP trunk is located.

    <Frame>
      <img alt="SIP country selection" />
    </Frame>
  </Step>

  <Step title="Verify Setup">
    Make a test call to your number to verify inbound calling, then use the test call feature to verify outbound calling.
  </Step>
</Steps>

## Security Requirements

<Warning>
  Your SIP credentials need to be secure. Your password must have at least 12 characters, include numbers, upper and lowercase letters, and special characters are recommended.
</Warning>

## Common Issues

<AccordionGroup>
  <Accordion title="Outbound calls not working?">
    * **Verify the SIP URI** — Make sure you copied the correct regional SIP URI from Step 2. Remove any trailing spaces.
    * **Check your username** — The username is the numeric SIP account number (e.g., `12345`), not your email address or account name.
    * **Check your password** — Ensure the password in Autocalls matches exactly what you set in the DIDLogic SIP account settings.
    * **Verify IP whitelist** — Make sure `34.195.177.252` is added to the authorized IPs in your DIDLogic SIP account.
  </Accordion>

  <Accordion title="Inbound calls not working?">
    * **Verify the SIP URI destination** — In DIDLogic, make sure the destination is set to SIP URI (not SIP device) and the format is correct: `<number_without_plus>@5wed79aeavr.sip.livekit.cloud`
    * **Check the IP whitelist in Autocalls** — Make sure the IP address you added in the Autocalls inbound settings matches the regional gateway you are using. Refer to the gateway IP table in Step 4.
  </Accordion>
</AccordionGroup>

***

<Note>
  Need help setting up? Our support team specializes in helping customers
  integrate their phone systems. We'll guide you through the entire process,
  ensuring a smooth setup with your specific phone system configuration.
</Note>


# Overview
Source: https://docs.autocalls.ai/provisioning/sip-trunking/sip-integration

Connect your existing phone system and numbers to Autocalls.ai

<Note>
  This guide will help you understand and set up SIP integration. If you need
  clarification during setup, our support team is available to assist.
</Note>

## What is SIP Integration?

SIP (Session Initiation Protocol) integration allows you to connect your existing phone system to Autocalls.ai. Think of it as building a bridge between your current phone setup and our AI platform. This means you can:

* Use your existing phone numbers with our AI assistants
* Keep your current phone system and provider
* Make and receive calls through your existing setup
* Maintain full control of your numbers
* Reduce carrier costs by using local VoIP providers with better rates

## How It Works

When you integrate your phone system with Autocalls.ai:

1. **Inbound Calls**: Calls to your numbers are routed through your phone system to our AI assistants
2. **Outbound Calls**: Our AI assistants can make calls appearing from your numbers
3. **Management**: You keep managing your numbers through your current provider
4. **Cost Efficiency**: Leverage your VoIP provider's competitive rates for call termination

## Integration Options

You can connect your phone system to Autocalls.ai in two ways:

### 1. PBX Extension Integration

This is like giving our AI platform an "extension" on your phone system:

* **What it is**: Connect a specific extension from your PBX/phone system
* **Perfect for**:
  * Testing the integration
  * Routing specific extensions to AI
  * Simple setup with existing phone systems
* **You'll need**:
  * Your extension number (e.g., 1000)
  * Extension username and password
  * Your PBX server address (e.g., pbx.yourcompany.com)

**Real-world example**:

```
Your office uses extensions 1001-1010 for staff
You set up extension 1011 for the AI assistant
Calls to 1011 go to the AI
The AI can make calls appearing as extension 1011
```

### 2. Direct Number Integration

This connects specific phone numbers to our platform:

* **What it is**: Route one or more of your phone numbers to our AI
* **Perfect for**:
  * Dedicated AI phone lines
  * Customer service numbers
  * Sales or support lines
* **You'll need**:
  * Your phone number (e.g., +1 555 0123)
  * SIP credentials from your provider
  * Provider's SIP server address

**Real-world example**:

```
You have a support number: +1 555 0123
You connect this number to our AI
All calls to +1 555 0123 are handled by the AI assistant
The AI makes outbound calls showing +1 555 0123
```

## Authentication & Call Flow

### Bidirectional Configuration

The SIP integration uses the same credentials for both inbound and outbound calls:

* **Inbound Calls** (VoIP → Autocalls.ai):

  ```
  Your VoIP system authenticates using username/password
  ↓
  Calls reach our platform
  ↓
  AI assistant answers
  ```

* **Outbound Calls** (Autocalls.ai → VoIP):
  ```
  AI initiates call
  ↓
  Our platform authenticates to your VoIP using same username/password
  ↓
  Call reaches destination
  ```

### Credential Synchronization

For the integration to work properly:

1. The credentials you set in Autocalls.ai dashboard must match exactly with your VoIP configuration
2. The same username/password combination is used for both directions
3. Any changes to credentials must be updated in both systems

<Warning>
  If you change credentials in your VoIP system, remember to update them in
  Autocalls.ai dashboard (and vice versa) to maintain the connection.
</Warning>

## Setting Up Your Integration

### Step 1: Gather Your Information

For PBX Extension:

```
Extension number: e.g., 1000
Server address: e.g., pbx.company.com
Username: Your extension username
Password: Your extension password
```

For Direct Number:

```
Phone number: e.g., +1 555 0123
SIP server: e.g., sip.provider.com
Username: Provided by your phone company
Password: Provided by your phone company
```

### Step 2: Configure in Dashboard

1. Go to your Autocalls.ai dashboard
2. Navigate to **Your Phone Numbers**
3. Click "Integrate SIP trunk"

### Step 3: Select SIP Trunk Type

At the top of the form, select one of these trunk types:

* **SIP Extension** - Use this if you already have an existing SIP credential (an extension) provided by your VoIP provider.
* **Phone Number (DID)** - Use this if you want to integrate a dedicated Direct Inward Dial (DID) number instead of a generic SIP extension.

For PBX Extension:

```
Extension number: e.g., 1000
Username: Your extension username
Password: Your extension password
```

<img />

For Direct Number:

```
Phone number: e.g., +1 555 0123
Username: Provided by your phone company
Password: Provided by your phone company
```

<img />

### Step 4: Outbound Settings

These settings control how Autocalls.ai sends outbound calls through your SIP provider.

* **SIP Address** - Enter the address/server of the SIP trunk without the port.
* **Outbound Proxy (Fixed IP)** - Some SIP providers require calls to originate from a single, whitelisted IP address. Configure this as follows:
  * **Toggle ON** - If your SIP provider requires a fixed source IP, enable Outbound proxy will come from a fixed IP address. Autocalls.ai will then send all outbound requests through a known static IP.
    Use this option only if your provider explicitly requires a single source IP.
  * **Toggle OFF:** - If your provider accepts calls from any IP, leave this option off. In that case, Autocalls.ai will send calls from dynamic IPs.

```
SIP address: (e.g., pbx.company.com/sip.provider.com)
```

<img />

### Step 5: Number Format Configuration

This tells our system how to format phone numbers when making calls. Choose based on your provider's requirements:

1. **International with +**

   ```
   Format: +[country][number]
   Example: +1 202 555 0123
   SIP Request: sip:+12025550123@your.pbx.com
   ```

2. **International without +**

   ```
   Format: [country][number]
   Example: 1 202 555 0123
   SIP Request: sip:12025550123@your.pbx.com
   ```

3. **National format**
   ```
   Format: [local number]
   Example: 0741926265
   SIP Request: sip:0741926265@your.pbx.com
   ```

### Step 6: Inbound Settings

These settings determine how Autocalls.ai receives and authenticates inbound calls from your SIP provider.

1. **Our SIP Address** - Autocalls.ai assigns a unique inbound SIP URI `5wed79aeavr.sip.livekit.cloud`. Your SIP provider must be configured to send inbound calls to this address by pointing their outbound trunk or routing rule to this URI.
2. **IP Address (Whitelist IPs)** - If your SIP provider can send calls from a known set of public IP addresses, choose IP Address. Then add each provider IP to the whitelist under Inbound Authentication.
3. **Username and Password** - If your provider supports SIP auth, choose Username and password. The same credentials you entered under Outbound Settings (username/password) will be used to authenticate inbound calls. Make sure your provider’s PBX is configured to include those credentials.

<img />

### Step 7: Country Selection

Select the country where your SIP trunk is provisioned.

<img />

### Step 8: Verify Setup

After configuration:

1. Make a test call to your number/extension
2. Check that the AI assistant answers
3. Use the test call feature to verify outbound calling

## Security Requirements

Your SIP credentials need to be secure:

* **Username**: Your extension number or provider-supplied username
* **Password must have**:
  * 12 or more characters
  * Numbers
  * Upper and lowercase letters
  * Special characters recommended

## Common Questions

<AccordionGroup>
  <Accordion title="Can I use multiple numbers?">
    Yes! You can integrate multiple extensions or direct numbers with our platform.
  </Accordion>

  <Accordion title="Will I lose control of my numbers?">
    No, you maintain full control through your current provider. The integration
    only establishes a connection between your system and our platform.
  </Accordion>

  <Accordion title="Can I still use my numbers for regular calls?">
    Yes, you can set up routing rules in your phone system to decide which calls
    go to the AI and which go to your regular phone system.
  </Accordion>

  <Accordion title="What if I need to change settings later?">
    You can update your integration settings anytime through the dashboard. All
    configuration options remain accessible after initial setup.
  </Accordion>

  <Accordion title="How does this help with call costs?">
    By using your own VoIP provider, you can take advantage of their local rates
    and existing agreements, which are often more competitive than standard carrier
    rates. This is especially beneficial for international calls.
  </Accordion>
</AccordionGroup>

***

<Note>
  Need help setting up? Our support team specializes in helping customers
  integrate their phone systems. We'll guide you through the entire process,
  ensuring a smooth setup with your specific phone system configuration.
</Note>


# Telnyx Integration
Source: https://docs.autocalls.ai/provisioning/sip-trunking/telnyx

A step by step guide to connect your Telnyx phone numbers via SIP trunking

This guide walks you through connecting your Telnyx phone numbers using SIP trunking. You'll create an FQDN connection in Telnyx, configure outbound authentication, assign your numbers, and import them into the platform.

<Tip>
  **One-time setup:** You only need to create the SIP connection once (Steps 1–5). For each additional phone number after that, you simply assign it to your existing connection (Step 5) and import it (Step 7).
</Tip>

<Info>
  **Why FQDN?** The connection type must be **FQDN** — not Credentials or IP Address. Credential connections require SIP REGISTER for inbound calls, which our platform doesn't send. FQDN connections route inbound calls directly to our SIP server and authenticate outbound calls via credentials.
</Info>

## Step 1: Create SIP Connection

1. Log in to the [Telnyx Mission Control Portal](https://portal.telnyx.com)
2. Navigate to **Real-Time Communications** → **Voice** → **SIP Trunking**
3. Click **Create SIP Connection**
4. **Name**: Choose a name (e.g., `my-company SIP trunk`)
5. **Type**: Select **FQDN**
6. Click **Create** — this opens the setup wizard

   <Frame>
     <img alt="Create SIP Connection in Telnyx" />
   </Frame>

## Step 2: Authentication and Routing

The wizard takes you to the **Authentication and routing** step. Here you'll add the FQDN for inbound call routing and set up outbound credentials.

### Add FQDN

1. Click **"+ Add FQDN"** and enter:
   * **DNS Record Type**: `A`
   * **FQDN**: `5wed79aeavr.sip.livekit.cloud`
   * **Port**: `5060`
2. Click **Save**

   <Frame>
     <img alt="Add FQDN to Telnyx connection" />
   </Frame>

### Inbound Calls Routing

Scroll down to the **Inbound calls routing** section on the same page:

1. **SIP subdomain**: Enter a name (e.g., `yourcompany`) — this creates `yourcompany.sip.telnyx.com`
2. **Receive SIP Subdomain calls**: Set to **From Anyone**
3. **Primary FQDN**: Select `5wed79aeavr.sip.livekit.cloud` from the dropdown

   <Frame>
     <img alt="Configure inbound calls routing" />
   </Frame>

### Outbound Authentication

Scroll down further to the **Outbound calls authentication** section:

1. **Method**: Select **Credentials**
2. Set a **username** and **password** — save these, you'll need them when importing the number into the platform

   <Frame>
     <img alt="Set outbound credentials" />
   </Frame>

Click **Next** at the bottom of the page.

## Step 3: Configuration

The wizard shows the **Configuration** page with connection details, webhooks, and advanced settings.

You don't need to change anything here — just verify that the **Type** shows **FQDN Connection** and click **Next**.

<Frame>
  <img alt="Configuration page" />
</Frame>

## Step 4: Inbound and Outbound

The wizard will go through the **Inbound** and **Outbound** steps. Since you already configured these in Step 2, verify the settings are correct and click **Next** on each.

On the **Outbound** page, make sure:

1. **Outbound voice profile**: Select your profile (or "Default")
2. **Localization country**: Select your country
3. **Channel limit**: Set to `10` or higher

   <Frame>
     <img alt="Configure outbound settings" />
   </Frame>

<Note>
  If you don't have an Outbound Voice Profile, go to **Voice** → **Settings** → **Outbound Voice Profiles** → **Create Profile**. Make sure to enable the countries you want to call under **Allowed Destinations**.
</Note>

## Step 5: Assign Numbers

The last step of the wizard is the **Numbers** page:

1. Click **Assign numbers**
2. Select the phone number(s) you want to use

## Step 6: Enable Geographic Permissions

1. Go to **Voice** → **Settings** → **Outbound Voice Profiles**

2. Click on edit

   <Frame>
     <img alt="Enable geographic permissions" />
   </Frame>

3. Click on your profile → **Allowed Destinations**

4. Enable the countries/regions you need to call

   <Frame>
     <img alt="Enable geographic permissions" />
   </Frame>

<Warning>
  If you skip this step, outbound calls will fail with a `403` error: **"Dialed number is not included in whitelisted countries."**
</Warning>

## Step 7: Import Number to the Platform

1. Go directly to the Phone Numbers page in your dashboard:

   **[https://app.autocalls.ai/phone-numbers](https://app.autocalls.ai/phone-numbers)**

   If it takes you to the login page, log in first — it will automatically redirect you to the Phone Numbers page.

2. Click **"Integrate SIP trunk"** (top-right corner of the page)

   <Frame>
     <img alt="Import number via SIP trunk" />
   </Frame>

3. Fill in your phone number and SIP credentials:

   ```
   Phone number: Your Telnyx number (e.g., +1 555 0123)
   Username: The outbound username from Step 2
   Password: The outbound password from Step 2
   ```

4. Enter the outbound settings:

   ```
   SIP address: sip.telnyx.com
   Outbound format: International (with + in front)
   ```

   <Frame>
     <img alt="Configure outbound settings in Autocalls" />
   </Frame>

<Warning>
  **SIP address must be `sip.telnyx.com`** — do NOT use your SIP subdomain (e.g., `yourcompany.sip.telnyx.com`). The subdomain is only for inbound routing on the Telnyx side. Using it as the outbound SIP address will result in `404 Not Found` errors.
</Warning>

5. Select **Authorization type**: **IP Address** and add the Telnyx IP addresses for your region:

   * **US**: `192.76.120.10`
   * **Europe**: `185.246.41.140` and `185.246.41.141`
   * **Australia**: `103.115.244.145` and `103.115.244.146`

   <Frame>
     <img alt="Configure inbound IP addresses" />
   </Frame>

<Note>
  You can add all IP addresses regardless of region — only the relevant ones will be used.
</Note>

6. Select the **country** where your SIP trunk is located.

   <Frame>
     <img alt="SIP Country selection" />
   </Frame>

## Step 8: Verify Setup

To test your Telnyx number, you need to assign it to AI assistants. Inbound and outbound require **separate assistants**:

### Test Inbound

1. Go to **AI Assistants** → create a new assistant (or use an existing one)
2. Set the assistant type to **Receive phone calls**
3. Assign your Telnyx phone number to the assistant
4. Call your Telnyx number from any phone — the AI assistant should answer

### Test Outbound

1. Create a **second assistant** with type **Make phone calls**
2. Assign the same Telnyx phone number to this assistant
3. Click **Speak to assistant** → **Phone call** — the platform will call your personal phone using the Telnyx number

<Warning>
  A single assistant cannot handle both directions. You need one **Receive phone calls** assistant and one **Make phone calls** assistant, both with the same phone number assigned.
</Warning>

## Security Requirements

Your SIP credentials need to be secure:

* **Username**: Your provider-supplied username
* **Password must have**:
  * 12 or more characters
  * Numbers
  * Upper and lowercase letters
  * Special characters recommended

## Common Issues

<AccordionGroup>
  <Accordion title="Dialed number is not included in whitelisted countries">
    Go to **Voice** → **Settings** → **Outbound Voice Profiles** → your profile → **Allowed Destinations** and enable the destination country you're trying to call.
  </Accordion>

  <Accordion title="Inbound calls not working or 'number is incorrect'">
    * Make sure the connection type is **FQDN** (not Credentials or IP Address)
    * Verify the FQDN is set to `5wed79aeavr.sip.livekit.cloud` on port `5060`
    * Check that the phone number is assigned to the FQDN connection (not another connection)
  </Accordion>

  <Accordion title="Outbound calls not connecting">
    * Verify the SIP address is `sip.telnyx.com` (not your SIP subdomain)
    * Check that credentials match between Telnyx and the platform
    * Make sure an **Outbound Voice Profile** is attached to the connection
    * Verify the **Localization country** is set correctly
  </Accordion>

  <Accordion title="Why can't I use Credentials connection type?">
    Credential connections require SIP REGISTER for inbound calls. Our platform uses direct SIP routing (no registration), so FQDN connection type is required. FQDN still supports credential-based authentication for outbound calls.
  </Accordion>
</AccordionGroup>

***

<Note>
  Need help setting up? Our support team specializes in helping customers
  integrate their phone systems. We'll guide you through the entire process,
  ensuring a smooth setup with your specific phone system configuration.
</Note>


# Twilio Integration
Source: https://docs.autocalls.ai/provisioning/sip-trunking/twilio

A step by step guide to connect your Twilio phone numbers via Elastic SIP Trunking

This guide walks you through connecting your Twilio phone numbers using Elastic SIP Trunking. You'll create a SIP trunk in Twilio, assign your numbers to it, and import them into the platform.

<Tip>
  **One-time setup:** You only need to create the Elastic SIP Trunk once (Step 1). For each additional phone number after that, you simply add it to your existing trunk (Step 2) and import it (Step 3).
</Tip>

## Step 1: Create Elastic SIP Trunking

1. Log in to your [Twilio Console](https://console.twilio.com)

2. In the **search bar** at the top of the dashboard, type **"Elastic SIP Trunking"** and click the result

   Alternatively, click the **"..."** menu on the left sidebar for **All Products & Services**, then scroll down and click **Elastic SIP Trunking**

3. Click **Create new SIP Trunk** and give it a **Friendly name** (e.g., `autocalls`)

   <Frame>
     <img alt="Create Elastic SIP Trunking" />
   </Frame>

### Configure Termination (for outbound calls)

4. In the left sidebar, click **Termination**
5. In the **Termination SIP URI** field, enter only a unique name — for example, `yourcompany`

   Twilio automatically appends `.pstn.twilio.com`, so your full URI will be: `yourcompany.pstn.twilio.com`

   <Frame>
     <img alt="Setup Termination" />
   </Frame>

<Warning>
  **Only enter the name part** (e.g., `yourcompany`). The `.pstn.twilio.com` suffix is pre-filled by Twilio. Do not paste a full URI or a localized URI (like `london-ix`) into the input field — this will create a malformed address that won't work. The general URI automatically routes traffic to the nearest region.
</Warning>

<Note>
  **Save this URI** — you will need the full Termination SIP URI (`yourcompany.pstn.twilio.com`) later when importing the number in Step 3.
</Note>

6. For your SIP trunk to accept outbound requests, you need to set up authentication. Scroll down to **Authentication** and configure IP Access Control Lists:

   Currently the SIP server does not have a static IP, so you need to whitelist all the IP addresses in the range:

   <Frame>
     <img alt="Twilio New Access Control" />
   </Frame>

   <Frame>
     <img alt="Twilio New Access Control" />
   </Frame>

### Configure Origination (for inbound calls)

7. In the left sidebar, click **Origination**
8. Click **Add new Origination URI** and enter the SIP server address:

   ```
   sip:5wed79aeavr.sip.livekit.cloud
   ```

   <Frame>
     <img alt="Setup Origination" />
   </Frame>

## Step 2: Assign Numbers to Your SIP Trunk

Now assign your Twilio phone numbers to the trunk you just created.

1. In your SIP trunk, click **Numbers** in the left sidebar
2. Click **Add a Number** and select the phone number(s) you want to use

   <Frame>
     <img alt="Move numbers to Elastic SIP Trunking" />
   </Frame>

<Tip>
  For future numbers, you only need to repeat this step and Step 3 below. The trunk configuration from Step 1 is already done.
</Tip>

## Step 3: Import Numbers to the Platform

Now import the number so the platform knows how to route calls.

1. Go directly to the Phone Numbers page in your dashboard:

   **[https://app.autocalls.ai/phone-numbers](https://app.autocalls.ai/phone-numbers)**

   If it takes you to the login page, log in first — it will automatically redirect you to the Phone Numbers page.

2. Click **"Integrate SIP trunk"** (top-right corner of the page)

   <Frame>
     <img alt="Import numbers via SIP trunk" />
   </Frame>

3. Fill in your phone number and SIP credentials:

   ```
   Phone number: e.g., +1 555 0123
   Username: Your extension username
   Password: Your extension password
   ```

   <Frame>
     <img alt="Fill in your details based on your integration type" />
   </Frame>

4. Enter the **Termination SIP URI** you created in Step 1:

   ```
   Server address: e.g., yourcompany.pstn.twilio.com
   ```

   <Frame>
     <img alt="Twilio Connect Number via SIP" />
   </Frame>

5. Select the **Authorization type**. If you configured IP-based authentication in Step 1, select IP and add these addresses:

   ```
   54.244.51.0
   54.244.51.1
   54.244.51.2
   54.244.51.3
   54.172.60.0
   54.172.60.1
   54.172.60.2
   54.172.60.3
   ```

   <Frame>
     <img alt="Credentials IP Type" />
   </Frame>

6. Select the **country** where your SIP trunk is located.

   <Frame>
     <img alt="SIP Country selection" />
   </Frame>

## Step 4: Verify Setup

After configuration:

1. Make a test call to your number
2. Check that the AI assistant answers
3. Use the test call feature to verify outbound calling

## Security Requirements

Your SIP credentials need to be secure:

* **Username**: Your extension number or provider-supplied username
* **Password must have**:
  * 12 or more characters
  * Numbers
  * Upper and lowercase letters
  * Special characters recommended

## Common Issues

<AccordionGroup>
  <Accordion title="Do I need to set up Elastic SIP Trunking for every new number?">
    No. You only create the Elastic SIP Trunk once (Step 1). For each new number, simply assign it to your existing trunk (Step 2) and import it into the platform (Step 3).
  </Accordion>

  <Accordion title="After connecting, inbound works but outbound does not work?">
    * **Check your Termination SIP URI** — make sure there are no spaces and it reads correctly (e.g., `yourcompany.pstn.twilio.com`). Verify you only entered the name part in Twilio and didn't accidentally include a localized URI or duplicate the `.pstn.twilio.com` suffix.
    * **Check your username and credentials** — the username is **not** the same as the "Friendly name" in the credential list. Double-check you entered the actual username.

    <Frame>
      <img alt="Twilio outbound not work" />
    </Frame>
  </Accordion>

  <Accordion title="How do I set up dialing to international countries?">
    1. In the Twilio Console search bar, search for **"geo"** to find **Voice Geographic Permissions**.

    <Frame>
      <img alt="Twilio setup dialing international" />
    </Frame>

    2. Choose **"Elastic SIP Trunking"** in the selector, then select the countries you want to dial.

    <Frame>
      <img alt="Twilio choose Elastic SIP Trunking for international dialing" />
    </Frame>
  </Accordion>
</AccordionGroup>

***

<Note>
  Need help setting up? Our support team specializes in helping customers
  integrate their phone systems. We'll guide you through the entire process,
  ensuring a smooth setup with your specific phone system configuration.
</Note>


# Zadarma Integration
Source: https://docs.autocalls.ai/provisioning/sip-trunking/zadarma

A step by step guide to connect your Zadarma phone numbers via SIP trunking

This guide walks you through connecting your Zadarma phone numbers using SIP trunking. Zadarma offers two connection types — **PBX** and **SIP Direct** — and the setup differs slightly for each.

<Tip>
  **Which type do you have?** If you use Zadarma's virtual PBX with extensions (e.g., 100, 101), you have **PBX**. If you use a standalone SIP account without a PBX, you have **SIP Direct**.
</Tip>

Select your connection type below and follow the steps:

<Tabs>
  <Tab title="PBX">
    ## Step 1: Gather Your SIP Credentials

    1. Log in to your [Zadarma Dashboard](https://my.zadarma.com)
    2. Go to **My PBX** → **Extensions**

    <Frame>
      <img alt="Zadarma My PBX Extensions" />
    </Frame>

    3. Find your extension and note these details:

    ```
    Extension: e.g., 510000-100
    Server address: pbx.zadarma.com
    Username: Your extension username (e.g., 510000-100)
    Password: Your extension password
    Phone number: Your phone number (e.g., +521151900966)
    ```

    <Frame>
      <img alt="Zadarma PBX Extension Settings" />
    </Frame>

    ## Step 2: Set Up External Server (for inbound calls)

    To receive inbound calls, you need to configure an **External Server** in Zadarma that forwards incoming calls to the platform's SIP server.

    1. In your [Zadarma Dashboard](https://my.zadarma.com), go to **Settings** → [**Virtual phone numbers**](https://my.zadarma.com/dirnum/active/)

    <Frame>
      <img alt="Zadarma Settings Virtual phone numbers" />
    </Frame>

    2. Find the number you want to connect and click the **gear icon** to open its settings

    <Frame>
      <img alt="Zadarma Settings Virtual phone numbers Gear Icon" />
    </Frame>

    3. Click **External Server** and enable the **SIP URI** checkbox

    <Frame>
      <img alt="Zadarma PBX External Server SIP URI configuration" />
    </Frame>

    4. Enter the SIP server address using your **phone number with the `+` prefix**:

    ```
    +YOUR_PHONE_NUMBER@5wed79aeavr.sip.livekit.cloud
    ```

    For example, if your number is `+551151900966`:

    ```
    +521151900966@5wed79aeavr.sip.livekit.cloud
    ```

    <Frame>
      <img alt="Zadarma PBX Server Address configuration" />
    </Frame>

    5. Click **Show IP** below the server address to reveal Zadarma's IP addresses (e.g., `185.45.152.216`, `185.45.155.33`)

    <Frame>
      <img alt="Zadarma PBX Show IP button" />
    </Frame>

    <Frame>
      <img alt="Zadarma PBX IP addresses revealed" />
    </Frame>

    <Note>
      **Save these IPs** — you will need them in Step 3 when configuring inbound authorization in the platform.
    </Note>

    <Warning>
      **PBX users must use the phone number with `+`** in the External Server address. Using the PBX extension number (e.g., `533177-100`) will **not** work for inbound calls.
    </Warning>

    ## Step 3: Import Numbers to the Platform

    Now import the number so the platform knows how to route calls.

    1. Go directly to the Phone Numbers page in your dashboard:

       **[https://app.autocalls.ai/phone-numbers](https://app.autocalls.ai/phone-numbers)**

       If it takes you to the login page, log in first — it will automatically redirect you to the Phone Numbers page.

    2. Click **"Integrate SIP trunk"** (top-right corner of the page)

    <Frame>
      <img alt="Import numbers via SIP trunk" />
    </Frame>

    3. Fill in your phone number and SIP credentials:

    ```
    Phone number: e.g., +551151900966
    Username: Your PBX extension (e.g., 533100-100)
    Your SIP Extension: Your phone number (e.g., +551151900966)
    Password: Your PBX extension password
    ```

    <Warning>
      **PBX users:** The **Username** is your PBX extension (e.g., `533100-100`). The **"Your SIP Extension"** field must be your **phone number** — this must match the number you used in the External Server address in Step 2.
    </Warning>

    <Frame>
      <img alt="PBX Extension credentials" />
    </Frame>

    4. Enter the **Server address** for outbound calls:

    ```
    pbx.zadarma.com
    ```

    <Frame>
      <img alt="Zadarma outbound server address" />
    </Frame>

    5. Select the **Authorization type**. Select **IP** and add the Zadarma IP addresses you noted earlier from **Show IP** in Step 2.

    <Frame>
      <img alt="Zadarma IP Authorization" />
    </Frame>

    6. Select the **country** where your SIP trunk is located.

    <Frame>
      <img alt="SIP Country selection" />
    </Frame>

    ## Step 4: Verify Setup

    1. Make a test call to your number
    2. Check that the AI assistant answers
    3. Use the test call feature to verify outbound calling
  </Tab>

  <Tab title="SIP Direct">
    ## Step 1: Gather Your SIP Credentials

    1. Log in to your [Zadarma Dashboard](https://my.zadarma.com)
    2. Go to **Settings** → **SIP Connection**

    <Frame>
      <img alt="Zadarma SIP Settings" />
    </Frame>

    3. Note these details:

    ```
    Server address: sip.zadarma.com
    Extension: Your SIP extension number (e.g., 247000)
    Username: Your SIP username (the same as your extension e.g., 247000)
    Password: Your SIP password
    ```

    <Frame>
      <img alt="Zadarma SIP Connection Settings" />
    </Frame>

    ## Step 2: Set Up External Server (for inbound calls)

    To receive inbound calls, you need to configure an **External Server** in Zadarma that forwards incoming calls to the platform's SIP server.

    1. In your [Zadarma Dashboard](https://my.zadarma.com), go to **Settings** → [**Virtual phone numbers**](https://my.zadarma.com/dirnum/active/)

    <Frame>
      <img alt="Zadarma SIP Settings Virtual phone numbers" />
    </Frame>

    2. Find the number you want to connect and click the **gear icon** to open its settings

    <Frame>
      <img alt="Zadarma SIP Settings Virtual phone numbers Gear Icon" />
    </Frame>

    3. Click **External Server** and enable the **SIP URI** checkbox

    <Frame>
      <img alt="Zadarma SIP External Server SIP URI configuration" />
    </Frame>

    4. Enter the SIP server address using your **SIP extension number**:

    ```
    YOUR_EXTENSION@5wed79aeavr.sip.livekit.cloud
    ```

    For example, if your extension is `247000`:

    ```
    247000@5wed79aeavr.sip.livekit.cloud
    ```

    <Frame>
      <img alt="Zadarma SIP URI" />
    </Frame>

    5. Click **Show IP** below the server address to reveal Zadarma's IP addresses (e.g., `185.45.152.216`, `185.45.155.33`)

    <Frame>
      <img alt="Zadarma SIP Show IP button" />
    </Frame>

    <Frame>
      <img alt="Zadarma SIP IP addresses revealed" />
    </Frame>

    <Note>
      **Save these IPs** — you will need them in Step 3 when configuring inbound authorization in the platform.
    </Note>

    ## Step 3: Import Numbers to the Platform

    Now import the number so the platform knows how to route calls.

    1. Go directly to the Phone Numbers page in your dashboard:

       **[https://app.autocalls.ai/phone-numbers](https://app.autocalls.ai/phone-numbers)**

       If it takes you to the login page, log in first — it will automatically redirect you to the Phone Numbers page.

    2. Click **"Integrate SIP trunk"** (top-right corner of the page)

    <Frame>
      <img alt="Import numbers via SIP trunk" />
    </Frame>

    3. Fill in your phone number and SIP credentials:

    ```
    Phone number: e.g., +1 555 0123
    Your SIP Extension: Your SIP extension number (e.g., 247000)
    Username: Your SIP username (the same as your extension e.g., 247000)
    Password: Your SIP password
    ```

    <Frame>
      <img alt="SIP Direct credentials" />
    </Frame>

    4. Enter the **Server address** for outbound calls:

    ```
    sip.zadarma.com
    ```

    <Frame>
      <img alt="Zadarma SIP outbound server address" />
    </Frame>

    5. Select the **Authorization type**. Select **IP** and add the Zadarma IP addresses you noted earlier from **Show IP** in Step 2.

    <Frame>
      <img alt="Zadarma IP Authorization" />
    </Frame>

    6. Select the **country** where your SIP trunk is located.

    <Frame>
      <img alt="SIP Country selection" />
    </Frame>

    ## Step 4: Verify Setup

    1. Make a test call to your number
    2. Check that the AI assistant answers
    3. Use the test call feature to verify outbound calling
  </Tab>
</Tabs>

## Security Requirements

Your SIP credentials need to be secure:

* **Username**: Your extension number or provider-supplied username
* **Password must have**:
  * 12 or more characters
  * Numbers
  * Upper and lowercase letters
  * Special characters recommended

## Call Transfer Limitations

<Warning>
  **Zadarma does not support SIP REFER**, which means standard cold transfer will not work out of the box. Warm transfer works automatically — the platform handles it via SIP INVITE.

  For **cold transfer**, you can use the **Custom SIP Transfer** option in your assistant's transfer settings. Set the custom SIP URI to:

  ```
  sip:+DESTINATION_NUMBER@sip.zadarma.com
  ```

  For example: `sip:+15557654321@sip.zadarma.com`

  Make sure the number is in international E.164 format with the `+` prefix. Do **not** use `tel:` URI format.
</Warning>

## Common Issues

<AccordionGroup>
  <Accordion title="Inbound calls are not working">
    * **Check your External Server address** — make sure the format matches your connection type:
      * **PBX**: `+YOUR_PHONE_NUMBER@5wed79aeavr.sip.livekit.cloud` (phone number with `+`)
      * **SIP Direct**: `YOUR_EXTENSION@5wed79aeavr.sip.livekit.cloud` (extension number)
    * **Verify the External Server is enabled** in Zadarma's settings
    * **Check that the "Your SIP Extension" field** in the platform matches: phone number for PBX, extension for SIP Direct
  </Accordion>

  <Accordion title="Outbound calls are not working">
    * **Check the Server address** — it should be `pbx.zadarma.com` for PBX or `sip.zadarma.com` for SIP Direct
    * **Verify your credentials** — make sure the username and password match what's shown in your Zadarma SIP settings
    * **Check your Zadarma balance** — outbound calls require sufficient credit
  </Accordion>

  <Accordion title="Cold transfer is not working">
    Zadarma does not support SIP REFER. To enable cold transfer:

    1. Go to your assistant's **Transfer Phone Call** tool settings
    2. Enable **"Custom SIP transfer"** (under Advanced)
    3. Set the SIP URI to `sip:+DESTINATION_NUMBER@sip.zadarma.com`

    If cold transfer still fails, verify the destination number is in international format with `+`.
  </Accordion>

  <Accordion title="Which connection type should I use — PBX or SIP Direct?">
    * **PBX** is recommended if you need multiple extensions, call routing rules, IVR menus, or other PBX features in Zadarma
    * **SIP Direct** is simpler if you just need a single number connected without PBX features

    Both work equally well for inbound and outbound AI calls.
  </Accordion>
</AccordionGroup>

***

<Note>
  Need help setting up? Our support team specializes in helping customers
  integrate their phone systems. We'll guide you through the entire process,
  ensuring a smooth setup with your specific phone system configuration.
</Note>


# Supported Countries
Source: https://docs.autocalls.ai/provisioning/supported-countries

Learn about phone number availability and provisioning across different countries

# Phone Number Availability

Autocalls.ai can provide phone numbers in **any country**. There are two ways to get a number:

## 1. Instant Provisioning

Numbers in these regions are available directly from your dashboard:

* United States
* Canada
* United Kingdom
* Most Western European countries
* Australia
* New Zealand
* And more...

Simply go to **Phone Numbers** in your dashboard and select from the dropdown.

## 2. Custom Provisioning

Need a number in a country not shown in the dropdown? No problem! We can help:

1. Contact us via the live chat
2. Let us know:
   * Which country you need
   * How many numbers
   * Your use case (inbound/outbound)
3. We'll handle the provisioning process for you

## Documentation Requirements

* **Standard Countries** (in dropdown): Usually just basic account verification
* **Other Countries**: May need:
  * Business registration
  * Local address
  * Industry-specific licenses
  * Other compliance documents

We'll guide you through exactly what's needed for your specific case.

## Timeframes

* **Dropdown Countries**: Instant provisioning
* **Custom Provisioning**: Usually 1-3 business days, depending on:
  * Country requirements
  * Document verification
  * Local regulations

***

**Need a specific number?** Just reach out via live chat, and we'll help you get set up in any country you need!


# Product Updates
Source: https://docs.autocalls.ai/releases/index

Latest features, improvements, and announcements from the Autocalls team

<Note>
  **Stay up to date** — Follow our latest product updates and improvements. We ship new features regularly to enhance your AI calling experience.
</Note>

<Update label="v1.10.2" description="Aug 30 2026">
  ### 🎙️ New Voice Models: ElevenLabs v3, Sonic 3.6 & Inworld TTS-2

  <Frame>
    <img alt="Image" />
  </Frame>

  ### 🎙️ Three New Generations of Voice. All Live Today.

  This is the biggest jump in voice quality we've ever shipped in a single update. The three best text-to-speech engines in the world all released a new generation, and all three are now available to your assistants: **ElevenLabs v3 Conversational**, **Cartesia Sonic 3.6**, and a brand new provider, **Inworld**.

  The difference is not subtle. These models breathe, pause, emphasise the right word, and stop sounding like something reading a script out loud. If you've ever had a caller ask "is this a robot?", play them one of these.

  ### 🔊 ElevenLabs v3 Conversational

  The most expressive voice available anywhere right now, and it speaks **every single language we offer**.

  * **Natural delivery** — real intonation, natural pauses, emotion that matches what's being said.
  * **Every language** — the older Flash v2.5 model covers 32 languages. v3 covers the full list.
  * **Works with multi-language assistants** — if your assistant speaks a main language plus extra ones, v3 handles all of them on the same voice.
  * Slightly slower to start speaking than Flash. On most calls you won't notice; if every millisecond counts, Flash v2.5 is still there.

  ### 🌊 Cartesia Sonic 3.6

  The most natural-sounding Cartesia model yet, and the widest language coverage on the platform: **44 languages**.

  * **Warmer, more human delivery** than Sonic 3.5, with better handling of long sentences and names.
  * **Works with multi-language assistants** — same as ElevenLabs v3, one voice covers your main language and your extra ones.

  ### ✨ Inworld: A Brand New Voice Provider

  A completely new provider joins the list, with two models so you can pick your trade-off:

  * **TTS-2** — the most accurate pronunciation and intonation we've heard, especially on names, addresses, and numbers. This is the one to use when the assistant has to get details exactly right.
  * **TTS-2 Flash** — the same voices and the same languages, tuned to start speaking faster. Ideal for high-volume calling where response speed matters most.

  Inworld voices are for assistants that speak **one** language. If your assistant has extra languages configured, choose ElevenLabs or Cartesia instead. The voice picker handles this for you.

  ### 🎛️ How to Switch (and What Happens to the Old Models)

  Nothing changed on your existing assistants. They're still on the model they were already using, and they'll keep working exactly as before.

  * **Switch when you're ready** — open an assistant, go to the voice settings, and pick the model right under the voice.
  * **Test before you commit** — place a test call to your own phone after switching. Takes thirty seconds and you'll hear the difference immediately.

  **Heads up:** the older versions (ElevenLabs Flash v2.5, Cartesia Sonic 3.5) will be **retired soon** in favour of the new generation. But we'd suggest moving over now while you can do it on your own schedule and listen to the result.

  ### 🗣️ Better Transcription Too

  Soniox, one of the speech recognition options, moved to its **v5 real-time model**. Fewer misheard words, better with accents, and quicker to react when a caller starts talking.

  ### 📚 Import Voices From the Provider Voice Libraries

  You're no longer limited to the voices already on the platform. You can now browse the full public voice libraries of the providers and **import any voice you like** straight into your account, ready to use on any assistant.

  ### 🛠️ Improvements and Fixes

  * **Human takeover on Messenger and Instagram** — if you reply to a customer from Facebook or Instagram directly, the assistant now steps back automatically instead of talking over you, and the whole conversation stays in one thread in your inbox.
  * **Dashboard no longer warns about unsaved changes it invented** — leaving a dashboard you hadn't edited used to pop up a "you have unsaved changes" warning. Gone. You can also dismiss the update notice now.
  * **Choosing new voice models over the API** — the new model names are available through the API and through connected AI apps, so you can set them when creating or updating an assistant there too.
</Update>

<Update label="v1.10.1" description="Aug 21 2026">
  ### 🪄 Simple Mode: Your First Assistant in Five Steps

  <Frame>
    <img alt="Image" />
  </Frame>

  Building an assistant used to mean facing one long form with every setting on it. There's now a second way in: a **five-step guided setup** that asks you plain questions and picks the technical parts for you.

  * **What it does** — pick a goal: answer calls, book appointments, take orders and reservations, call and qualify leads, confirm and remind, or ask for feedback. Then pick your industry. Each goal sets up the right kind of assistant behind the scenes.
  * **Your business** — tell it who you are. Paste your website and it reads the page for your hours, services and prices instead of making you type them out.
  * **Its voice** — choose the language it speaks and the voice it uses. Pick more than one language and it automatically selects a setup that can actually understand all of them, not just the first.
  * **What it knows** — connect your calendar so it can check real availability before offering a time. Cal.com, GoHighLevel and Calendly all connect right there in the flow.
  * **What it says** — the call script is written for you from everything you entered. Read it, change any line, or ask for a rewrite in your own words.

  At the end you land on an **overview sheet**: one page showing what your assistant does, what it sounds like, and what it's connected to. From there you can place a test call to your own phone, listen to it, and change the script by chatting with it, without ever opening the full form.

  **Where to find it:** create a new assistant and you'll be offered **Simple** or **Advanced**. You can switch between the two at any time. Nothing about the full form has changed, and anything you build in Simple Mode opens normally in Advanced.
</Update>

<Update label="v1.10.0" description="Aug 16 2026">
  ### 📞 WhatsApp Voice Calls

  <Frame>
    <img alt="Image" />
  </Frame>

  This is the big one. Your assistant can now take and place real voice calls **over WhatsApp**, on the same numbers you already use for messaging. Your customer taps the call button in the chat they already have with you, and the assistant picks up. No phone dialling, no roaming charges on their side, no separate app.

  * **Customers calling you**: anyone can call your WhatsApp number at any time and your assistant answers automatically, day or night.
  * **You calling customers**: WhatsApp asks for consent first. Send an **Ask to call** request inside the conversation, and once the customer taps *Allow*, you can call them for the next 7 days.
  * **One toggle per number**: open a WhatsApp sender, switch calling on, and the platform sets everything up for you. Before it turns on, you see exactly which assistant will be answering.
  * **Same call, same tools**: WhatsApp calls behave like any other call. Recording, transcript, post-call analysis, tools, and knowledge base all work the way they already do.
  * **Everything in one place**: WhatsApp calls show up in your calls list with their own icon, and the call also appears inside the chat thread, so the message history and the call history read as one conversation.
  * **It tells you when it can't**: if a contact isn't callable yet, or a number isn't eligible for calling, you get a plain-language reason instead of a silent failure.

  **Where to find it:** **Channels → WhatsApp**, open a sender, then **Enable calling**. There's a built-in **WhatsApp Calling** guide on the same page covering the rules below.

  ### 🎙️ Import Voices Straight from the Voice Libraries

  You're no longer limited to the voices already on the list. You can now browse the full voice libraries of the built-in voice providers and import any voice you like into your account with one click. It then shows up in the voice picker for every assistant, like all the others.

  ### 💬 Channels and Inbox

  * **Ignore message reactions**: a new per-number setting so a thumbs-up on your message doesn't wake the assistant up and trigger a reply.
  * **Web widget stays put**: the widget settings panel no longer closes on you every time you save.
  * **Group widgets by campaign**: custom dashboard widgets can now filter and group by campaign name.
  * **Instagram setup instructions**: connecting an Instagram account now comes with step-by-step instructions in the app, plus a fix for connection screens that failed to load on some accounts.
  * **Mobile menu fix**: opening plans or credits on a phone now closes the side menu behind it.

  ### 🛠️ Improvements and Fixes

  * **Deleting a lot of records at once**: large deletions of calls, leads, campaigns, or conversations now run in the background instead of making you wait on a loading screen or timing out.
  * **Warm transfers, three fixes**: the assistant no longer introduces the caller twice, the briefing to the person receiving the call is no longer skipped, and recordings of transferred calls are now saved correctly.
  * **Bringing your own number**: importing a number no longer fails when a matching setup already exists at your carrier.
</Update>

<Update label="v1.9.1" description="Jul 27 2026">
  ### 🤖 Connect AI Now Builds Your Automations

  <Frame>
    <img alt="Image" />
  </Frame>

  Connect AI already let you build and fix assistants by chatting with ChatGPT or Claude. It can now build your **automations** too: the workflows that run before, during and after a call.

  You describe what should happen in plain language. The AI picks the trigger, wires the steps, finds your sheets, campaigns and numbers by name, runs a real test, and switches the automation on only if it passes. No builder screens, no field names, no IDs to copy.

  ### 💬 What That Looks Like

  Things you can now ask for, word for word:

  * *"After every call, if the caller was qualified, add a row to my Google Sheet with their name, phone and summary."*
  * *"If a customer asks to be called back later, call them back at the time they asked for."*
  * *"Give me a link my website form can post leads to, and call every new lead automatically."*
  * *"During a call, let the assistant look up an order number in my system and read the status back to the caller."*
  * *"Let callers cancel or reschedule their appointment while they're on the phone."*
  * *"Before the assistant offers a discount, text my supervisor and only continue once they approve."*

  Each one becomes a live, tested automation attached to the assistant you name.

  ### 📚 17 Ready-Made Automations

  The AI checks a library of proven automations first, so common requests are set up in seconds instead of built from scratch:

  * **Save qualified leads to a spreadsheet**, or **log every call to your CRM**
  * **Call the customer back** at the exact time they asked for
  * **Hot lead alerts**, **SMS or WhatsApp follow-ups**, and **transcript emails** after a call
  * **Call new leads automatically** from a web form, ad platform or spreadsheet
  * **Confirm or remind before a booking**, and cancel or reschedule mid-call
  * **Recognise returning callers** and greet them by name
  * **Ask a human for approval** before the assistant does something sensitive

  Start from one of these, then change it by chatting.

  ### 🔗 Connects to What You Already Use

  Spreadsheets, email, calendars, chat apps, CRMs and hundreds of other services are available as steps. Anything without a ready-made connector is still reachable with a plain web request, so your own internal tools work the same way.

  Accounts are connected once on the **Automate** page under Connections. After that the AI picks your sheet, your pipeline or your page **by name** from what's actually in your account.

  ### 🛡️ It Tests Before It Goes Live

  An automation that looks right but quietly does nothing is worse than no automation. So nothing switches on until it has actually run.

  * **A real test run, not a preview**: the automation is executed end to end with a realistic sample of your own data. Only a green run gets attached to your assistant.
  * **You approve anything that really sends**: if the test would send a message, place a call or send an email for real, you're told first and asked to confirm, using your own number or address.
  * **Safe repairs**: if a change to a live automation fails its test, the previous working version is restored automatically so the automation keeps running. You can roll back any change yourself too.
  * **No silent overwrites**: an assistant that already has an automation for the same event won't get it quietly replaced.

  ### 🔍 Fix What's Already Running

  Ask what went wrong and the AI reads the execution history for you: every run, what each step received and returned, and exactly which one failed and why. Once the cause is fixed, the run can resume from the broken step, so steps that already succeeded are never repeated and nothing gets sent twice. Repairs change only what needs changing and leave the rest of your setup intact.

  ### 🛠️ Also Worth Knowing

  * **Available on your API too**: if you'd rather build from your own code than by chatting, the same create, test, update, roll back and run history operations are exposed as endpoints.

  **Where to find it:** open **Connect AI** from the top bar to link your account, then just ask. Everything the AI builds also appears on your **Automate** page, where you can open and edit it visually at any time.
</Update>

<Update label="v1.9.0" description="Jul 26 2026">
  ### 💬 Facebook & Instagram Messages, 📣 SMS + WhatsApp Campaigns, 🔐 Two-Factor Authentication

  💬 Facebook Messenger and Instagram Messages

  <Frame>
    <img alt="Image" />
  </Frame>

  Your assistant can now answer people who write to you on **Facebook Messenger** and **Instagram**, the same way it already handles WhatsApp and web chat.

  * **Connect in a few clicks**: link your Facebook Page or Instagram account, pick the assistant that should reply, and you're live.
  * **Everything in one inbox**: Messenger and Instagram conversations land in the same inbox as your other channels. You can read the full thread, jump in yourself, and take over from the assistant at any point.
  * **Open in Meta**: one click takes you straight to the original conversation on Facebook or Instagram when you need to handle something there.
  * **Connection health at a glance**: each connection shows its current status, and reconnecting after a password or permission change is a single button.

  🔐 Two-Factor Authentication and a Real Security Center

  <Frame>
    <img alt="Image" />
  </Frame>

  Your account now has proper protection against someone getting in with just a stolen password.

  * **Two-factor authentication**: turn on a second step at login using an authenticator app, or get a one-time code by email if you'd rather not install anything.
  * **Trusted devices**: mark the computer you use every day as trusted so you're not asked for a code on every login. Remove a device any time and it starts asking again.
  * **Active sessions**: see every browser and device currently signed in to your account, with location and last activity, and sign any of them out with one click.
  * **Security activity**: a running log of logins, password changes, and security settings changes, so you can spot anything you don't recognise.
  * **Identity confirmation**: sensitive actions now ask you to confirm it's really you before going through.

  **Where to find it:** the new **Security** page in your account settings.

  📣 Campaigns Now Send Text Messages Too

  <Frame>
    <img alt="Image" />
  </Frame>

  Campaigns are no longer calls only. You can now run the same lead lists through **SMS** and **WhatsApp**.

  * **Pick a channel**: when you create a campaign, choose whether it places calls, sends WhatsApp messages, or sends SMS.
  * **Schedule it in advance**: set a start date and time and the campaign switches itself on when the moment arrives. No need to be at your desk.
  * **Track every message**: sent messages and replies show up on the campaign and on each lead, so you can see exactly what went out and what came back.
  * **Better date and time picker**: choosing when a campaign runs is now clearer and harder to get wrong.

  🧭 New Channels Hub

  <Frame>
    <img alt="Image" />
  </Frame>

  All your messaging channels now live in one place. Voice, WhatsApp, SMS, web chat, Messenger, and Instagram are grouped under a single **Channels** page, each with its own colour and status, so connecting a new one or checking what's already active takes seconds instead of hunting through menus.
</Update>

<Update label="v1.8.3" description="Jul 22 2026">
  ### 🧠 New AI Models: GPT-5.6 (Luna & Terra)

  Your assistants can now run on **OpenAI's newest GPT-5.6 models**, the latest generation of the AI that understands each request and decides how your assistant responds. Expect sharper reasoning, better instruction-following, and more natural handling of longer, multi-step conversations.

  Available in two variants, **GPT-5.6 Luna** and **GPT-5.6 Terra**. Both are live now in ***pipeline mode***. Pick either one from the model list when you create or edit an assistant.
</Update>

<Update label="v1.8.2" description="Jul 14 2026">
  ### 🔇 Turn Off Interruptions in Speech-to-Speech and Dualplex

  The **Allow interruptions** setting now works in every conversation mode, not just Pipeline.

  Until now, Speech-to-speech and Dualplex assistants were always interruptible: if the caller made any noise while the assistant was talking, it would stop mid-sentence. You can now switch interruptions off in those modes too, so the assistant finishes what it's saying without being cut short by background noise, TV sound, or someone talking in the room.

  **Where to find it:** Assistant settings, **Allow interruptions?** toggle. Leave it on for natural back-and-forth conversations. Turn it off when the assistant has to deliver something in full, like disclaimers, confirmations, opening hours, or a list of options.
</Update>

<Update label="v1.8.1" description="Jul 8 2026">
  ### 🧠 GPT Realtime 2.1 & 2.1 Mini: Now in Speech-to-Speech & Dualplex & WhatsApp Media

  ### 🧠 New Voice Models: GPT Realtime 2.1 & 2.1 Mini

  Your **speech-to-speech** and **Dualplex™** assistants can now run on OpenAI's newest voice models. **GPT Realtime 2.1** follows your prompt more reliably and sounds more natural on names, numbers, and interruptions. **GPT Realtime 2.1 Mini** is a lighter, faster option for high-volume or simpler assistants.

  Both are live now. Pick either one from the model list in any speech-to-speech or Dualplex™ assistant.

  ### 💬 Send Media on WhatsApp

  You can now send images, audio, video, and documents in your WhatsApp messages, not just text. Add a caption or filename and send straight from the inbox or the API.
</Update>

<Update label="v1.8.0" description="Jun 23 2026">
  ### 🚀 Build & Manage Your Assistants Right Inside ChatGPT & Claude

  <Frame>
    <img alt="Image" />
  </Frame>

  This is a big one. You can now connect your account to **ChatGPT** and **Claude** and run your whole AI calling setup just by chatting — no dashboards, no setup screens. Tell the AI what you want in plain language and it does the work for you, from start to finish.

  **What you can do once it's connected:**

  * **Build a new assistant from scratch** — Describe what you need ("an assistant that books appointments") and the AI creates it for you: it writes the prompt, picks a natural voice, sets a greeting, and even adds the tools the assistant needs, like checking a calendar and booking slots.
  * **Fix and improve an existing assistant** — Ask it to review an assistant's prompt and settings. It points out what's weak and applies the fixes for you.
  * **Analyze your calls** — "Look at my last call and tell me what went wrong." It reads the full transcript and the call evaluation, explains what to improve, then updates the assistant to match.
  * **Learn from your history** — Ask it to study your last 30 calls, spot patterns, and tune your assistant so it performs better next time.
  * **Launch calling campaigns** — It walks you through setting up an outbound campaign from your leads and starts it for you.
  * **Handle the day-to-day** — Manage phone numbers, leads, and knowledge bases, or send a message — all from the same chat.

  **🔗 How to connect it (about a minute):**

  * Open the new **Connect AI** button in your dashboard and copy your secure connection link.
  * In ChatGPT or Claude, go to the connectors settings and choose **Add custom connector**, then paste the link. A built-in, step-by-step guide with screenshots walks you through both apps.
  * Sign in to your account and approve. Your tools appear in the AI app, and you're connected.

  It's secure by design: the connection only works after **you** sign in and approve it with your own account, and every action runs with your existing permissions. Nothing happens that you haven't logged in for.

  **Try it:** open a fresh chat and type *"Create an appointment-booking assistant."* Within seconds the AI has built it, written the prompt, given it a voice and a greeting, wired up calendar booking, and offered to place a test call.

  ### ⚡ Reliability & Fixes

  * **Smoother call transfers** — More reliable transfers between assistants, including when an assistant hands off to book a meeting.
  * **Faster chat under load** — Increased capacity for handling chat conversations during busy periods.
  * **Independent dashboard tables** — Tables on the dashboard no longer interfere with each other when you page through them.
</Update>

<Update label="v1.7.11" description="Jun 16 2026">
  ### 🔌 Connect External Tools with MCP, 🛠 Redesigned Mid Call Tools, ⚡ One-Click Automation Linking

  🔌 Connect External Tools to Your Assistant (MCP)

  <Frame>
    <img alt="Image" />
  </Frame>

  Your assistant can now plug into outside tools and live data through **MCP (Model Context Protocol)**, the open standard for connecting AI to external systems. Instead of building tools one at a time, you connect a whole toolset in a single step. Point your assistant at a compatible server (a CRM, your internal APIs, a knowledge tool) and it can look things up and take action **right in the middle of a conversation**, on voice calls, the web widget, and chat alike.

  * **Add a server in minutes, no code** — Paste the server address and (if needed) an authentication header. There's nothing to install and nothing to build
  * **Tools discovered automatically** — The moment you connect, every tool the server offers is detected and listed, with its description and parameters, so you can see exactly what your assistant can do
  * **Pick precisely what's exposed** — Turn individual tools on or off per server, so an assistant only gets the abilities you want it to have
  * **Connect once, reuse everywhere** — Assign one server to a single assistant or to many, and manage them all from a dedicated page
  * **Always know the status** — Each server shows a live "connected" indicator, lists its available tools, and gives a clear message (with a one-click re-test) if anything needs attention
  * **Secure by design** — Authentication tokens are stored encrypted, and you stay in control of which tools and permissions each assistant can reach

  Popular uses include connecting a CRM to look up contacts and create deals mid-call, querying your own systems for live order or account data, or wiring in a documentation tool so the assistant can answer detailed questions accurately.

  🛠 Redesigned Call Actions — Easier to Build, Easier to Understand

  <Frame>
    <img alt="Image" />
  </Frame>

  The tools that let your assistant **do things during a conversation** (look up an order, send an SMS, book an appointment, check availability, submit a form) got a full redesign. The whole experience is now built so that anyone can set up a working action, even with no technical background and no coding.

  * **Visual flow card** — A new step-by-step layout shows exactly how an action works, from the information the assistant collects to the response it gets back, all in one clear view
  * **"How it works" guidance built in** — Plain-language explanations sit right next to each setting, so you always understand what an action does and when your assistant will reach for it
  * **System variables at your fingertips** — Drop in live details like the caller's phone number or the current date and time straight into your action, with a handy reference so you never have to guess the right name
  * **One home for everything** — Custom actions and connected MCP servers now live together on a single, redesigned Tools page that's far easier to work with

  ⚡ Build Call Actions with No-Code Automations

  <Frame>
    <img alt="Image" />
  </Frame>

  This is the big one. You no longer need an API or a developer to give your assistant a custom action. When you create an action, you can now choose the **Automation Platform** option, and the platform builds the entire technical connection for you.

  * **The connection is created automatically** — Pick "Automation Platform" and a linked automation is generated and wired up for you instantly. The web address that connects it to your assistant is set and locked behind the scenes, so there are no IDs to copy, paste, or keep in sync
  * **Build the logic visually** — Open the linked automation and drag together whatever steps you need: look up a record, check a calendar, send a message, run several actions in a row. When you're done, you simply finish with a **"Return Response"** step to hand the result back to the assistant on the call
  * **Multi-step workflows made simple** — Anything that used to require custom code (chaining several systems together, transforming data, conditional logic) can now be assembled with no code at all
  * **Smart linking for existing automations** — If you paste in an automation you've already built, the platform recognizes the workflow on its own and pulls in its details automatically, so connecting it takes seconds

  The result: from "the assistant should be able to do X" to a working, live action in minutes, entirely point-and-click.

  ### 🎙 Voice & Call Reliability

  * **Cleaner call endings** — Fixed a case where the assistant could repeat itself or hesitate when wrapping up a call
  * **Voice picker polish** — Follow-up fixes to the new voice picker for smoother selecting
</Update>

<Update label="v1.7.10" description="Jun 7 2026">
  ### 📁 Assistant Folders & Labels, New Voice Picker, WhatsApp Human Takeover

  ### 🗂 Assistant Folders & Labels — Organize Your Workspace

  If you manage more than a handful of assistants, finding the right one just got much easier. You can now organize assistants into **folders** and tag them with **color-coded labels**.

  * **Folder tabs** — The assistants list now shows tabs for each folder (plus an "All" view), with a searchable dropdown when you have many folders
  * **Labels for cross-cutting tags** — Each assistant can carry multiple labels (for example "Production", "Testing", "Client X"), shown as badges on the assistant cards and filterable from the list
  * **Bulk actions** — Select multiple assistants and move them to a folder or add/remove labels in one go
  * **Create on the fly** — New folders and labels can be created right from the assistants page, no detour through settings
  * **Full API support** — Folders and labels can be managed via the API, and assistants can be assigned on create or update

  ### 🎙 New Voice Picker — Find the Perfect Voice in Seconds

  The voice dropdown is gone. Choosing a voice now opens a **full picker** built for browsing hundreds of options without scrolling through an endless list.

  * **Filter by gender, age, and accent** — Narrow the catalog to exactly the kind of voice you're looking for, with free-text search on top
  * **Provider tabs** — Voices are grouped by speech engine, and each card shows a provider badge so you always know what you're selecting
  * **Language-aware** — The picker follows your assistant's language and warns you before selecting a voice that doesn't support it
  * **Clone voices in place** — The voice cloning option now lives inside the picker, and deleting a cloned voice uses a proper styled confirmation
  * **Smarter syncing** — Selecting a voice automatically sets the matching speech engine on the assistant, so there's nothing to configure twice

  ### 🏷 Phone Number Nicknames

  Phone numbers can now have a **nickname and a color**, so "the support line" stops being "+1 555 0182 …which one was that again?"

  * **Visible everywhere** — Nicknames show up in the phone numbers list, assistant cards, call details, SMS history, and every place you select a number (assistant setup, warm transfers, campaign pools)
  * **Searchable selectors** — Find a number by its nickname or by the number itself
  * **API support** — Nicknames are included in all phone number responses and can be set via the API, including for SIP trunks

  ### 🤝 WhatsApp Coexistence — Automatic Human Takeover

  Coexistence mode gets its biggest quality-of-life upgrade yet: when someone on your team replies to a customer **directly from the WhatsApp Business app**, the AI now detects it and **automatically steps aside** for that conversation.

  * **No more talking over each other** — The moment a human takes over from the phone, the AI stops responding in that chat
  * **Clear audit trail** — A system note appears in the conversation explaining why the AI paused, so everyone knows what happened
  * **Voice notes & images fixed** — Audio messages and images from customers now come through reliably in Coexistence mode
  * **No charges for synced history** — When you connect an existing WhatsApp account, old conversations that stream in during setup are never billed

  ### 🔔 Webhook & Integration Upgrades

  The **conversation ended webhook** got a major upgrade for anyone building automations on top of chat conversations.

  * **Media attachments included** — Images, audio, and files exchanged in the conversation are now part of the webhook payload
  * **Conversation ID & timestamps** — The payload now carries the conversation ID and per-message timestamps (human-readable and unix), so transcripts can be reconstructed precisely
  * **Re-send with one click** — Every conversation now has a "Re-send webhook" action, and the delivery result (status and response) is stored so you can see exactly what your endpoint received
  * **Bulk actions** — Re-evaluate or re-send webhooks for many conversations at once, straight from the conversations list

  ### 🛠 Other Improvements & Fixes

  * **No more technical data read out loud** — In rare cases the AI could speak fragments of raw technical output mid-call when using tools; this is now stripped from both speech and transcripts
  * **Day separators in conversations** — Long chat histories now show date dividers, making it much easier to scan past conversations
  * **Chat widget button fix** — The small launcher button no longer appears clipped on some sites
  * **Webhook reliability** — Fixed a timing issue that could cause the conversation ended webhook to silently skip for some WhatsApp chats
  * **Template sender display** — WhatsApp templates now show their sender more clearly in the templates list
</Update>

<Update label="v1.7.9" description="May 22 2026">
  ### 👥 WhatsApp Coexistence, Smart Message Buffering, Engine upgrades

  ### 💬 WhatsApp Coexistence — Keep Using the WhatsApp Business App

  You can now connect a WhatsApp sender in **Coexistence mode**, which lets your team keep using the official WhatsApp Business app on their phones at the same time as the AI assistant. No need to migrate your existing chats, contacts, or labels — everything stays where it is, and the AI handles new conversations in parallel.

  This is a game-changer for businesses that already have an active WhatsApp Business setup and don't want to disrupt how their team works today.

  ### ⏱ Smart Message Buffering for WhatsApp

  Real customers don't send one perfectly composed message — they send three quick texts, an image, then a follow-up question. Until now, the AI would reply to each one separately, creating a clumsy back-and-forth. With the new **response delay** setting, the AI now waits a configurable number of seconds (0–300) before replying, giving customers time to finish their thought.

  * **Configurable per assistant** — Set the response delay individually on each assistant in the assistant form. Leave it at zero for the original instant-reply behavior

  ### 📞 New Outbound Call Limits Page

  To stay aligned with carrier compliance regulations on shared infrastructure numbers, the new **Limits page** (now in the user menu, next to "My profile") shows your current daily outbound call allowance, your usage so far today, and your trust tier at a glance.

  * **Inbound and SIP trunk calls are unlimited** — The limits only apply to outbound calls placed through shared platform numbers; bring-your-own carrier accounts are not affected
  * **Request a higher limit** — A request workflow is available directly from the page; verified businesses can be upgraded to higher tiers
  * **Bring your own carrier for unlimited outbound** — A prominent banner links to the BYO Telephony wizard for teams that want full control over their outbound volume
  * **Smart campaign handling** — Campaigns that hit the limit aren't paused or broken; they automatically resume the next day where they left off

  ### 🚀 Voice Engine Upgrade — Across-the-Board Quality & Stability

  The underlying voice engine has been upgraded. Customers should notice smoother calls, fewer mid-call hiccups, and faster response times across every voice mode.

  ### 🛠 Other Improvements & Fixes

  * **Delete campaigns via API** — A new DELETE /campaign/ endpoint lets you remove campaigns programmatically; running campaigns are stopped automatically before deletion
  * **Assistant transfer over API** — The *assistant\_transfer* tool now persists correctly when configured via the assistant API, and self-transfers (an assistant trying to transfer to itself) are blocked
  * **Mid-call tool test button** — Fixed the test button on mid-call tool configuration so it sends the correct HTTP method (GET, POST, etc.) instead of always defaulting
</Update>

<Update label="v1.7.8" description="May 10 2026">
  ### 🎙 OpenAI Realtime 2, GPT 5.5, Cartesia 3.5, Bring Your Own Telephony 1 click integration and more

  ### 🧠 GPT Realtime 2 — Better Prompt Following

  Our **speech-to-speech and Dualplex mode** now includes OpenAI's **GPT Realtime 2**. The biggest win: the assistant follows your prompt much more reliably — staying on script, respecting your instructions, and handling complex multi-step conversations without drifting.

  Combined with our proprietary **Dualplex™** technology, this delivers the best voice quality, lowest latency, and most reliable instruction-following available on any AI calling platform today.

  ### 🎙 Cartesia Sonic 3.5 — Voice Engine Upgrade

  The **Cartesia** voice engine has been upgraded to **Sonic 3.5**, the latest version. Expect noticeably more natural-sounding voices, better stability across long calls, and improved consistency on tricky words and names.

  The upgrade applies automatically to every assistant using Cartesia voices — no configuration changes needed.

  ### ⚡️ GPT-5.5 — New Language Model in Pipeline Mode

  You can now select **GPT-5.5** as the language model for your assistants in pipeline mode. It's a great all-rounder: fast responses, strong reasoning, and excellent prompt-following — ideal for assistants that need both speed and intelligence without the cost of the flagship models.

  Available right now in your assistant's pipeline mode configuration.

  ### 📞 Bring Your Own Telephony — Self-Service Carrier Imports

  You can now connect your own carrier accounts directly through a guided import wizard — no support ticket, no manual SIP setup. Teams that already have negotiated rates with their preferred provider can plug those accounts in and start dialing in minutes.

  * **Twilio SIP trunks** — Full self-service import with a step-by-step onboarding help panel that walks you through each setting
  * **Telnyx support** — Connect Telnyx accounts using the same wizard experience as Twilio
  * **Zadarma & DIDLogic** — Two more carriers added to the picker, giving you more flexibility on regions and pricing

  ### 🎤 Post-Call Re-Transcription for Dualplex™ & Multimodal Calls

  You can now automatically re-transcribe completed calls from the original recording at any time. Useful when you want to retry transcription with the most capable STT model.

  Re-transcription is available for both **Dualplex™** and multimodal assistants, with clear billing transparency built right into the assistant view.

  ### 📂 Split-View Detail Panels — Calls & Conversations

  The calls and conversations list pages now have a side-by-side detail panel. Click any record on the left, see the full details on the right — no more clicking back and forth. Reviewing dozens of calls or chats is suddenly a much smoother experience.

  * **Performance indexes added** — Navigating between records inside the panel is significantly faster, even on accounts with very high conversation volumes
  * **Extracted variables section** — Variables collected during the conversation are now displayed in a dedicated section on the conversation detail view

  ### 💬 Disable & Enable AI Per Conversation

  Two new API endpoints let you pause and resume the AI for a specific conversation programmatically — perfect for human handoffs in WhatsApp and chat workflows. When the AI is disabled, your agents take over; re-enable it whenever you're ready to hand back.

  ### 💸 Auto Top-Up for Chat Credits

  Chat credits can now top up automatically when balances run low, with email notifications keeping you informed of every refill. No more interrupted chat experiences because credits ran dry overnight.

  ### 🔄 Telephony & Call Flow Improvements

  * **Initial message on AI-to-AI transfers** — When a call is transferred to an AI agent, the agent now speaks its initial message immediately for a smoother handoff
  * **Transfer caller details visible** — Transfer-to and client phone numbers are now displayed on transfer calls in the call view
  * **Single-character tool parameter names** — Tool parameters can now use single-character names, useful for compact JSON schemas

  ### 🛠 Other Improvements & Fixes

  * **WhatsApp pre-verified number deletion** — Removing a pre-verified WhatsApp number now works correctly
  * **Phone number deletion** — Phone number deletion jobs now run reliably, with proper logging when something goes wrong
</Update>

<Update label="v1.7.7" description="Mar 30 2026">
  ### 🧠 Gemini 3.1 Flash Live, GPT Realtime 1.5 in Dualplex

  ### 🧠 Gemini 3.1 Flash Live — New Speech-to-Speech Model

  You can now run voice calls using **Google's Gemini 3.1 Flash Live** in speech-to-speech mode. This gives you another top-tier real-time voice option with excellent multilingual support and fast response times.

  ### ⚡ GPT Realtime 1.5 — Now with Dualplex™

  **GPT Realtime 1.5** now fully supports **Dualplex™** mode — our proprietary technology for the most natural-sounding AI phone calls. This means you get OpenAI's latest real-time model combined with superior interruption handling, smoother turn-taking, and lower perceived latency.

  ### 📊 Per-Turn Latency Metrics

  Every conversation now tracks **detailed latency metrics for each turn** — how long the assistant took to respond, broken down by processing step. Use this to spot slow turns, compare model performance, and fine-tune your setup for the fastest possible calls.

  ### 📈 Custom Dashboard Widgets

  Build your own dashboard with **customizable stat widgets**. Choose what data to display, apply percentage calculations, filter by time of day, and format with prefixes, suffixes, and abbreviations — all without writing code.

  ### 🛠️ Other Improvements

  * **Cleaner transcripts** — Control tokens and SSML tags are now automatically stripped from call transcripts for a cleaner read, with an optional toggle to show them for debugging
  * **Soniox for WhatsApp voice notes** — WhatsApp audio message transcription now uses Soniox for better accuracy
  * **Widget auto-open fix** — The web widget now remembers when a visitor closes it and won't pop up again during the same session
</Update>

<Update label="v1.7.6" description="Mar 24 2026">
  ### 🔀 Transfer to AI Assistant — Mid-Call Handoffs Between Specialized Agents

  <Frame>
    <img alt="Image" />
  </Frame>

  Your AI voice agent can now **transfer a live call to a different AI assistant** — mid-conversation, with zero interruption. The target assistant takes over with its own voice, language model, and transcription provider, so each step of the call gets the right specialist.**Why this matters:** Instead of building one massive assistant that handles everything, you can now create specialized agents for each stage of a call — a sales qualifier that hands off to a technical expert, a receptionist that routes to a scheduling specialist, or a triage agent that escalates to a support specialist.

  * **Seamless mid-call handoff** — the caller stays on the line while the conversation transfers to a different AI assistant with full context
  * **Full provider swap** — each assistant can use its own voice (ElevenLabs, Cartesia), language model (GPT-4o, GPT-5.4), and transcription engine
  * **Rich assistant selector** — choose the target assistant from a dropdown showing avatar, language, voice, and mode at a glance
  * **Works with the Flow Builder** — add assistant transfers as actions in your visual call flows alongside warm transfers, DTMF, and keypad collection

  **Example use case:** A dental clinic's receptionist AI answers the call, qualifies the patient, then transfers to a scheduling assistant that speaks the patient's language and books directly into the calendar — all in one seamless call.

  ### 📞 Warm Call Transfers — Now with Variable Injection

  Warm transfers just got smarter. When your AI agent transfers a call to a human supervisor, it can now **inject call variables** — like the caller's name, reason for calling, or qualification score — into the briefing. The supervisor picks up already knowing who's on the line and why.

  ### 🧠 GPT-5.4 Mini & Nano Models Available

  Two new language models are now available for your AI assistants:

  * **GPT-5.4 Mini** — faster responses at lower cost, ideal for simple call flows like appointment booking and FAQ handling
  * **GPT-5.4 Nano** — the fastest option for high-volume, low-complexity calls where speed matters most

  Select them from the Language Model dropdown when configuring your assistant. All existing prompts and tools work without changes.

  ### 🔧 Flow Builder Improvements

  The visual flow builder got several quality-of-life upgrades:

  * **New action types** — warm transfer, assistant transfer, DTMF input, and collect keypad are now available as flow actions
  * **Smarter action dropdown** — the dropdown now shows which tools are configured on your assistant, with warnings for unconfigured ones
  * **Edge delete on hover** — remove connections between nodes by hovering over the edge and clicking the delete button
  * **Import/export support** — save your flows as files and import them into other assistants or accounts
  * **UI fixes** — wider edit panel, fixed dropdown clipping, smoother animations
</Update>

<Update label="v1.7.5" description="Mar 16 2026">
  ### ✨ AI Assistant Advisor

  <Frame>
    <img alt="Image" />
  </Frame>

  Your AI assistants now have their own personal optimization coach. The new **AI Advisor** automatically analyzes your assistant's configuration and call performance, then gives you clear recommendations to improve call quality — with one-click fixes.

  Open any assistant and you'll see a smart banner telling you exactly how many settings could be improved. Click **"View & fix"** to open the full advisor panel.

  ### 💡 How It Works

  The advisor runs **41 intelligent rules** across three categories:

  * **Recommendations** — Settings that aren't optimal for your use case. Things like voice speed, temperature values, silence thresholds, and endpoint sensitivity. Each recommendation explains *why* it matters and what to change.
  * **Troubleshoot** — Experiencing issues on calls? Echo, interruptions, the AI not following your prompt, calls cutting off too early? Select the problem and the advisor shows exactly which settings to adjust.
  * **Best Settings** — A curated guide to the optimal configuration for each voice mode (Pipeline, Multimodal, and Dualplex).

  ### 🔧 One-Click Fix

  Every recommendation comes with a **"Fix"** button that automatically applies the optimal value — no manual editing needed. You can also hit **"Fix All"** to apply every recommendation at once. The advisor updates in real time as you make changes.
</Update>

<Update label="v1.7.4" description="Mar 7 2026">
  ### 🆕 New models: Soniox STT, Realtime 1.5, GPT 5.4 & 5.3

  ### 🎙️ Soniox — New Speech-to-Text Provider in Pipeline Mode

  We've added **Soniox** as a new speech-to-text engine available in pipeline mode. Soniox delivers improved transcription accuracy across multiple languages with noticeably lower latency, meaning your voice assistants understand callers faster and respond more naturally.

  You can select Soniox as your transcription provider when configuring any assistant **in pipeline mode** — give it a try and compare the results with your current setup.

  ### ⚡ GPT Realtime 1.5 — Speech-to-Speech mode Upgrade

  Our speech-to-speech mode now runs on **OpenAI's GPT Realtime 1.5**, bringing major improvements across the board:

  * **Better call quality** — More natural, fluid conversations with improved voice output
  * **Lower latency** — Faster responses for a smoother caller experience
  * **Improved prompt following** — The assistant stays on script more reliably and handles complex instructions better

  Select GPT Realtime 1.5 in your assistant's speech-to-speech mode configuration and hear the difference.

  ### 🧠 GPT-5.4 & GPT-5.3 — Latest OpenAI Models Now Available in Pipeline Mode

  You can now select **GPT-5.4** and **GPT-5.3** as the language model for your assistants in pipeline mode — OpenAI's newest and most capable models.

  * **GPT-5.4** — OpenAI's most factual model yet, with 33% fewer factual errors than its predecessor. Significantly better at following complex instructions, staying on script, and handling multi-step conversations. Your assistants will give more accurate, reliable answers and follow your prompts more precisely.
  * **GPT-5.3** — A strong all-rounder with excellent speed and reasoning balance. Great for assistants that need fast, smart responses.

  Both models are available right now — just select them in your assistant's pipeline mode configuration.

  ### 🛠️ Other Improvements

  * **AEC warmup** — A new parameter that pre-warms the acoustic echo cancellation, reducing audio artifacts at the start of calls
  * **Expanded API** — New endpoints for campaigns, WhatsApp, warm transfers, keypad collection, filler phrases, voice settings, and provider discovery — build your own integrations with full programmatic control
  * **Voice preview fix** — Cartesia voice previews now play correctly
  * **Web widget improvements** — Fixed mobile height and form input collection on auto-open
</Update>

<Update label="v1.7.3" description="Feb 23 2026">
  ### 🚀 WhatsApp Files & Audio, Cal.com EU + Teams, GDPR Data Retention, Chat Webhooks & Widget Customization

  ### 🔥 WhatsApp Gets Smarter: Vision, Audio Transcription & Media Attachments

  Your WhatsApp AI agents just got a massive upgrade: they can now **see images**, **transcribe voice messages**, and **handle file attachments** from your customers.

  **📸 Vision Support** — When a customer sends an image via WhatsApp, your AI agent can now analyze it using vision-capable LLMs (OpenAI, Claude, Gemini) and respond intelligently. Perfect for reading documents, analyzing property photos, diagnosing issues from images, or identifying products.

  **🎙️ Automatic Voice Message Transcription** — Customers who send WhatsApp voice notes no longer get ignored. Agents now automatically transcribe audio messages based on your assistant's language settings.

  **📎 Full Media Attachment Support** — All inbound media (images, audio, video, documents) are now securely stored as attachments. A new attachments gallery in the conversation detail view lets operators browse received files. Operators can also send files back to customers from the chat UI.

  ### 🔒 GDPR Data Retention

  Full GDPR-compliant data retention with **configurable retention periods** for calls, leads, conversations, and SMS. Set retention rules per account — data is automatically cleaned up on schedule so you stay compliant without lifting a finger.

  ### 📅 Cal.com v2 Integration Overhaul

  Completely rebuilt for the v2 API with **dynamic booking fields** and **team event types**.

  * **Region selector** — choose from EU, US, or custom Cal.com endpoint
  * **Dynamic booking fields** — reads your Cal.com event type's custom fields as-is, no more overwriting your configuration
  * **Team event types** — book into team calendars, not just personal ones
  * **Full backward compatibility** — existing configs continue working without changes
  * **Smart event picker** with grouped personal/team events and auto-fetched booking fields

  ### 💬 Chat Conversation Webhooks & Automation

  Chat conversations now fire **"conversation ended" triggers** on inactivity timeout. Payload includes full transcript, extracted variables, WhatsApp sender info, and AI evaluation using your post-call analysis schema. New automation platform trigger for "Conversation ended".

  ### 🎨 Widget Customization Upgrade

  * **Extra large layout** — half-screen panel, full-screen on mobile
  * **Translatable tab labels** — rename Voice/Chat tabs to match your brand
  * **Auto-open on page load** — widget expands automatically
  * **Custom avatar** — upload your own widget avatar
  * **Hide function calls** — LLM tool calls hidden from chat by default

  ### 🛠️ Improvements & Fixes

  * **Auto top-up locking** — prevents duplicate charges during concurrent top-up attempts
  * **WhatsApp logo sync fix** — resolved an issue where profile logos weren't syncing correctly
</Update>

<Update label="V1.7.2" description="Jan 26 2026">
  ### 🔥 New Call Features: Warm Transfers + Keypad Digits Collection

  We’ve added two major capabilities to make AI phone agents more reliable in real-world support and sales scenarios — smoother human handoff and faster, more accurate data capture.

  ☎️ Warm Call Transfer (Hold + Brief + Connect)

  <Frame>
    <img alt="Image" />
  </Frame>

  When a caller asks to speak with a human, your AI can now run a **true warm transfer**: it puts the customer on hold (with music or silence), dials a supervisor/agent, **briefs them with context**, and only then connects both sides.

  **Why it’s better**

  * ✅ **Context preserved:** agents don’t start cold — they already know what the customer needs.
  * 🎶 **Professional experience:** caller hears a hold message + hold music while the agent is reached.
  * 🔁 \*\*More compatible transfers:\*\***Web calls can now transfer to real human phone agents** (the initial interaction doesn’t need to be a phone call anymore).
  * For **SIP trunks without SIP REFER**, warm transfer now works by creating a new **SIP INVITE** and merging calls — no REFER required.

  **Configurable options** Supervisor number, caller ID mode, hold music/silence, hold message, supervisor briefing instructions, and the final “connected” message.

  ⌨️ Customer Keypad Digits Collection (DTMF)

  <Frame>
    <img alt="Image" />
  </Frame>

  Customers can now enter digits on their phone keypad during a conversation, and the assistant receives the input instantly and continues naturally.

  **How it works**

  * Runs **in the background** — no awkward pauses
  * Auto-submits after a configurable timeout (default **5s**)
  * Instant submit when the user presses **#** or \*\*\*\*\*
  * Works alongside voice: customers can **speak or type**

  **Perfect for** Account numbers, PINs, phone numbers, license plates, order codes — especially when accuracy and privacy matter.

  **Configurable options** Input timeout + submit key (# or \*).

  These upgrades make your assistants feel more human, more reliable, and easier to deploy in production support environments.
</Update>

<Update label="v1.7.1" description="Jan 10 2026">
  ### ↗️ WhatsApp External Numbers Integration

  You can now connect **external WhatsApp sender numbers;** like your own mobile number or SIP/business-owned lines and use them to **fully automate WhatsApp messaging** inside the platform.

  ### What’s included

  * 📲 **Bring your own sender**: use your existing number instead of being limited to platform-provisioned WhatsApp numbers
  * 🤖 **Inbound + outbound automation**: the AI can reply to incoming messages and send outbound follow-ups, reminders, and lead qualification messages
  * ✅ **Simplified onboarding** via Meta Embedded Signup with **OTP verification** (SMS/voice) — no complicated Meta setup guesswork

  ### Where you’ll find it

  Create a new WhatsApp sender from the platform and choose the **External Number** path. Once connected, you can submit message templates for approval to Meta and use your connected number to **send and receive WhatsApp messages** with AI handling the conversation end-to-end.

  This update unlocks a more “native” customer experience — your AI can operate at scale on WhatsApp while keeping your brand identity and sender number consistent.
</Update>

<Update label="v1.7.0" description="Jan 8 2026">
  ### ✍️ AI Prompt Writer, 🧩 Flow builder & 🟢 Whatsapp native integration

  This update packs three major upgrades that change how you build assistants end-to-end: **prompting becomes conversational**, **flows become visual**, and **WhatsApp becomes native** — with a setup that skips the usual Meta headaches.

  ## ✍️ AI Prompt Writer

  <Frame>
    <img alt="Image" />
  </Frame>

  Edit prompts by chatting with AI — no manual prompt engineering required.

  * **Conversational editing:** just say what you want (“make it more friendly”, “add return policy info”) and the AI updates your system prompt.
  * **Smart diff preview:** review changes before applying — additions, removals, and edits are clearly highlighted.
  * **Accept/reject control:** apply suggestions one-by-one or in bulk, so you stay in full control.
  * **Quick actions:** one-click improvements like *Make concise*, *Add detail*, *Improve clarity*.
  * **Variables + schema built-in:** manage pre-call variables (e.g. ) and define structured post-call extraction fields (string/number/boolean) without leaving the editor.
  * **Template library:** start from proven templates for sales, support, scheduling, surveys.

  Now you can refine assistant behavior quickly — without technical skills.

  ## 🧩 Flow Builder

  <Frame>
    <img alt="Image" />
  </Frame>

  Design conversation flows visually with drag-and-drop — perfect for production ready flows.

  * **Node-based builder (5 node types):** Start, Speak, Prompt, Action, End.
  * **Branching logic:** build multi-path conversations (Interested / Maybe / Not Interested) with clear outcomes.
  * **Settings panel:** customize agent personality (name, language, assertiveness, humor) per flow.
  * **Auto-layout:** one click to neatly organize your flow.
  * **Import/Export JSON:** share flows across assistants or teammates instantly.

  Build complex, multi-branch scripts without writing long prompts — faster iteration, cleaner structure, easier collaboration.

  ## 🟢 WhatsApp Native Integration

  <Frame>
    <img alt="Image" />
  </Frame>

  Connect your AI assistant to WhatsApp Business in minutes — and let it handle **both inbound and outbound messaging** automatically.

  ### ✅ Setup that’s actually easy

  Meta’s WhatsApp onboarding is notoriously complex (business setup, verification, templates, embedded signup, compliance). We’ve turned that into a guided flow so you can go from zero to live quickly:

  * Simple onboarding wizard that walks you through the required Meta steps
  * Platform-assisted setup that removes the usual guesswork and friction
  * You get WhatsApp running without spending days figuring out Meta’s process

  ### 🤖 AI-managed inbound + outbound WhatsApp

  Once connected, your assistant can:

  * Reply instantly to **incoming messages**
  * Send **outbound messages** proactively (follow-ups, reminders, confirmations, lead qualification)
  * Keep a consistent “brain” across channels — same assistant logic, same data, same tone

  ### 🔜 What’s coming next

  * **External numbers support (soon):** right now WhatsApp can be activated on **numbers from our platform**, but bringing your own number is coming next.
  * **WhatsApp calls support (soon):** we’re expanding from messaging to calls so you can handle the full lifecycle in one channel.

  Together, these updates make assistant-building dramatically faster—**design flows visually, refine behavior by chatting with AI, and deploy natively on WhatsApp** for end-to-end omnichannel automation.
</Update>

<Update label="v1.6.4" description="Dec 17 2025">
  ### 🚀 New Models, Chat Automations & Smarter Call Controls

  This release brings together **powerful new AI models**, **chat-based automation triggers**, and **advanced call behavior controls**, marking another big step forward for both voice and text experiences on the platform.

  ### 🤖 New & Updated AI Models

  ### **GPT-5.2 Now Available**

  We’ve released **GPT-5.2**, delivering improved reasoning and better instruction-following. For faster responses we recommend to continue using GPT-5.1

  ### **GPT Realtime Mini Upgrade**

  The realtime mini model has been bumped to: **gpt-realtime-mini-2025-12-15** This update improves stability and responsiveness in low-latency voice interactions.

  ### **New Gemini Native Audio Model (Speech-to-Speech)**

  Based on Google’s December 12, 2025 release, we’ve added: **gemini-2.5-flash-native-audio-preview-12-2025**

  You can find the new version as **Gemini 2.5 Flash Dialog New (Dec 2025)** and the previous version as **Gemini 2.5 Flash Dialog (Oct 2025)**

  * Better handling of **complex workflows** and function calls
  * Available in **speech-to-speech mode only**

  ⚡ **New Conversation Created Trigger**

  <Frame>
    <img alt="Image" />
  </Frame>

  You can now trigger automations **the moment a new chat conversation starts** on the **web widget**.

  * Instantly capture **pre-form input variables** such as name, email, phone number, or any custom fields you’ve defined.
  * Use this data to **create leads**, **sync contacts to your CRM**, **send notifications**, or start any custom automation flow.
  * Works seamlessly with the chat web widget, making text interactions just as automatable as voice calls.

  ### 📞 Smarter Call Prompts & Behavior

  ### 📨 **End Call on Voicemail – Custom Prompt**

  You can now define a **custom prompt** that the AI will use when leaving a voicemail. This gives you full control over tone, content, and messaging instead of relying on a generic message.

  ### 🔁 **Re-Engagement Prompt Setting**

  When the re-engagement interval is reached, the assistant can now use a **custom re-engagement prompt**. This allows you to fine-tune how the AI follows up after silence — making interactions more natural and context-aware.

  ### 🎧 Multiple Ambient Sound Options

  We’ve added **multiple ambient sound choices** for voice calls.

  <Frame>
    <img alt="Image" />
  </Frame>

  *As always, we’re excited to see what you build with these new capabilities.*
</Update>

<Update label="v1.6.3" description="Dec 14 2025">
  ### ⚙️ Automations Update & Calendly integration

  This release focuses on making **automation setup faster and smoother**, while expanding your assistant’s scheduling capabilities.

  🔄 **Simplified Data Injection for Automations**

  <Frame>
    <img alt="Image" />
  </Frame>

  Setting up automations is now much easier and more intuitive.

  * Previously, you had to fully build a flow, run a test call, and only then reference the latest data to configure your automations.
  * Now, with a single click on **“Load data”** when adding a trigger, the platform automatically fetches **all custom variables** defined in your assistant settings.
  * This includes both **input variables** and **post-call evaluation / extracted variables**, giving you a complete and accurate data structure from the start.

  The result: faster setup, fewer test calls, and a much smoother automation-building experience.

  📅 **Calendly Integration**

  <Frame>
    <img alt="Image" />
  </Frame>

  You can now connect **Calendly calendars** directly to your assistants.

  * Seamlessly book appointments through your AI flows.
  * Ideal for sales calls, consultations, demos, or service-based businesses.
  * Works alongside existing calendar integrations, giving you more flexibility in how and where you schedule.

  *These improvements remove friction from automation workflows and expand your scheduling options — helping you build, test, and deploy assistants more efficiently than ever.*
</Update>

<Update label="v1.6.2" description="Dec 8 2025">
  ### 🔊 New Models & Smart Tools Update

  This release brings\*\* upgrades\*\* to voice quality, transcription accuracy, and usability across the platform — along with a few handy workflow improvements.

  ### 🗣️ **Cartesia Sonic 3 (TTS) for Pipeline & Dualplex**

  Introducing **Cartesia Sonic 3**, our newest high-fidelity TTS engine with **voice cloning** support and advanced **emotion control**.

  * 🎭 Toggle **SAML tags** to adjust tone, emotion, and intensity in your AI’s voice.
  * 🎤 Clone and fine-tune voices directly within your assistants for natural, expressive conversations.

  ### ✍️ **ElevenLabs Scribe v2 Transcriber**

  We’ve added **Scribe v2**, a cutting-edge transcription model from ElevenLabs, now available in **Pipeline Mode**. Expect sharper accuracy, better punctuation, and faster transcription speeds — perfect for complex dialogues and noisy environments.

  ### 🎙️ **Record Voice Samples in-App**

  You can now **record voice samples directly inside the platform** for cloning. No need to upload pre-recorded files — just hit record, speak, and your voice sample will be ready to use in seconds.

  ### 🔁 **Deepgram Nova-3 Migration**

  All assistants using **Deepgram** have been automatically upgraded from **Nova-2 → Nova-3**, bringing:

  * Higher transcription accuracy
  * Better noise handling
  * Faster response times

  ### 🌐 **Web Widget Preview Sharing**

  You can now **copy a shareable preview URL** of your web widget — no need to embed it on a website first. Perfect for **demoing widgets** to clients or sharing with your team during testing.

  ### 🔄 **Bulk Resend Webhooks**

  Quickly **resend multiple webhooks** for past calls in one action. Ideal for syncing historical data, debugging integrations, or recovering missed events.

  These updates make your assistants **more powerful, expressive, and developer-friendly** — with the latest models and smarter workflow tools across the board.
</Update>

<Update label="v1.6.1" description="Nov 21 2025">
  ### 🧠 GPT-5.1, campaign level timezone and fixes

  🤖 **GPT-5.1 in Pipeline Mode**

  <Frame>
    <img alt="Image" />
  </Frame>

  We’ve added **GPT-5.1** — smarter, faster, and more context-aware than ever. Enjoy improved accuracy and response times across all your pipeline-based assistants.

  ### 🌍 **Campaign Timezone Settings**

  You can now set a **custom timezone per campaign**, ensuring calls and automations run exactly at the right local time for your audience.

  ### 🛠️ **General Improvements & Fixes**

  This update also includes multiple **stability, performance, and UI fixes** across the platform for a smoother experience overall.
</Update>

<Update label="v1.6.0" description="Oct 30 2025">
  ### 💬 Introducing AI Chat for Web Widget — A Major Step Toward Omnichannel Communication

  We’ve just reached a **huge milestone** in our mission to become a truly **omnichannel AI platform** for both **voice and text interactions**.

  With this release, your AI assistants can now **chat directly with users** through a **fully integrated web widget**, alongside voice mode. This unlocks an entirely new way for customers to engage with your AI — from websites, landing pages, and soon, across multiple messaging channels.

  ### 🧠 AI Chat Mode in Web Widget

  Assistants can now operate in **chat mode**, **voice mode**, or a **hybrid voice + chat mode**, allowing you to choose the ideal experience for your users.

  The web widget can be easily embedded on any website, giving your visitors instant access to your AI assistant for inquiries, bookings, or lead capture.

  **Coming soon:** support for **WhatsApp**, **SMS**, and **Meta Messenger**, making your assistant truly omnichannel.

  <Frame>
    <img alt="Image" />
  </Frame>

  ### 💬 Conversations View

  Just like you can see your **Call History**, you now have a dedicated section for **Chat Conversations** — view, search, and manage all customer chat interactions directly from the dashboard.

  Each conversation is logged with timestamps, user details, and message history, so you can track performance and customer engagement easily.

  <Frame>
    <img alt="Image" />
  </Frame>

  ### 🧩 Web Widget Pre-Form Builder

  Collect essential lead data **before** your assistant starts chatting or talking.

  You can now build **custom pre-chat forms** with a visual form builder, fully customizable for your business use case — whether that’s a salon appointment, a medical consultation, or a sales lead.

  ### Supported Field Types

  * **Text** – Single-line text input
  * **Email** – With built-in validation
  * **Phone** – With country selector
  * **Text Area** – For multi-line inputs

  ### Additional Settings

  * **Required fields** (ensure important info is captured)
  * **Variable names** sent directly to your assistant (e.g. **customer\_name**)
  * **Labels, placeholders, and helper text** for a clean, user-friendly interface

  <Frame>
    <img alt="Image" />
  </Frame>

  ### 🎨 Enhanced Widget Customization

  The web widget is now more flexible and on-brand than ever:

  * Choose between **Modern** or **Classic** styles
  * Adjust **size, placement, and colors**
  * Enable **voice-only, chat-only, or hybrid** interaction modes

  ### 💰 Pricing & Availability

  * **Free** when used **internally** for testing assistants (no balances deducted).
  * **Public chat mode** costs just **\$0.01 per AI reply**, regardless of the model or message size — making it one of the most cost-efficient AI chat options available.
</Update>

<Update label="v1.5.3" description="Oct 23 2025">
  ### 🌟 Custom dashboards, 💬 Assistant chat, 💳 Auto top-up, 📅 1-Click Cal.com integration

  We’re excited to roll out a series of powerful updates designed to make managing, testing, and customizing your AI assistant experience smoother than ever.

  📊 Custom Dashboards

  <Frame>
    <img alt="Image" />
  </Frame>

  Say hello to **fully customizable dashboards** built for your workflow.

  * **Drag and drop** charts, stats, and tables to design layouts that fit your business.
  * Display data from **calls, leads, campaigns, or any connected integrations**.
  * Add and resize widgets in real time to focus on what matters most — performance, revenue, or engagement trends.

  💬 Live Chat with Assistant

  <Frame>
    <img alt="Image" />
  </Frame>

  You can now **chat directly with your assistant in real time** using text — perfect for testing and refining conversation flows without making live calls.

  * 💡 **Free usage for testing:** Chats with your assistant don’t consume any balance, so you can experiment safely.
  * 🧠 Great for **training, debugging, or reviewing responses** before deploying changes to production.
  * 🚀 **Coming soon:** Extend live chat to customer-facing channels like your **website widget**, **WhatsApp**, **Messenger**, and **SMS**, allowing users to talk to the AI on their favorite platforms.

  This makes building and improving assistants faster, cheaper, and more accessible for every user.

  💳 Auto Top-Up

  <Frame>
    <img alt="Image" />
  </Frame>

  No more interruptions due to low balance. The new **Auto Top-Up** feature ensures your system always stays online and calling.

  * Get **real-time alerts** when your balance is running low.
  * Automatically **add credits** from your default payment method.
  * Set thresholds and amounts to stay in full control of your spending.

  It’s a simple but powerful way to guarantee uninterrupted service — especially for active campaigns or high-volume operations.

  🔗 Cal.com 1-Click Integration

  <Frame>
    <img alt="Image" />
  </Frame>

  Connecting your **Cal.com** account is now faster and simpler than ever.

  * Use the new **one-click connect** button to instantly link your calendar.
  * Built-in **troubleshooting tools** help you identify and fix sync issues quickly.
  * Perfect for ensuring your scheduling automations and booking workflows stay seamless across assistants and team calendars.

  📅 Set Date Format

  <Frame>
    <img alt="Image" />
  </Frame>

  You can now choose your **preferred date format** across the platform.

  * Select from common regional styles like DD/MM/YYYY or MM/DD/YYYY.
  * Improves clarity for reports, logs, and analytics — especially across global teams.
</Update>

<Update label="v1.5.2" description="Oct 13 2025">
  ### 📵 Blacklist, ♻️ Automatic number rotation, 🔁 Transfer call improvements and more

  We’ve rolled out several powerful updates to give you more control, visibility, and performance across your calls and assistants.

  📵 Blacklist System

  <Frame>
    <img alt="Image" />
  </Frame>

  Easily block unwanted numbers for both inbound and outbound calls.

  * Add numbers to your **Blacklist** directly from **Calls History** or **Leads** (single or bulk).
  * Calls to or from blacklisted numbers are automatically rejected with a clear message: *“Number is blacklisted.”*
  * View, manage, or remove entries via the new **Blacklist** panel.

  📞 Campaign Number Pool

  <Frame>
    <img alt="Image" />
  </Frame>

  Campaigns can now use **multiple outgoing numbers**.

  * Assign several numbers to a campaign.
  * Calls are automatically rotated and balanced between numbers for even distribution.
  * Built with fast and efficient number rotation algorithm.

  🔁 Transfer Call View

  <Frame>
    <img alt="Image" />
  </Frame>

  A clearer way to track transferred calls.

  * See all **transferred calls** directly in the Calls table with detailed info like parent call, duration, and outcome.
  * Available for calls made through **dedicated numbers** or the **“Use your own number”** feature. ***SIP trunk integrated calls cannot be tracked for call transfers.***

  ### 🤖 Gemini 2.5 Model October version

  Introducing the latest **Gemini 2.5** model released in October for **Speech-to-Speech** mode.

  * Smarter and more accurate with **improved function-calling abilities**.
  * Will soon be integrated into **Dualplex Mode** for an even better assistant experience.
</Update>

<Update label="v1.5.1" description="Sep 8 2025">
  ### 📅 Multi-Calendar Support for Assistants

  We’ve added **Multi-Calendar Tools**, making scheduling smarter and more flexible than ever.

  ### What’s new:

  * 🧑‍🤝‍🧑 **Team & Service Calendars** – Assign different calendars to the same assistant, perfect for businesses where customers choose a specific team member or service (e.g. hair vs. nails in a salon).
  * 🩺 **Medical Appointments Made Easy** – Patients can now book directly with the right doctor’s calendar, streamlining scheduling in clinics and practices.
  * 🔄 **Seamless Management** – Assistants handle multiple calendars effortlessly, reducing back-and-forth and ensuring accurate bookings every time.

  This update makes your AI assistants even more versatile, whether you’re running a **salon, clinic, or service team**.
</Update>

<Update label="v1.5.0" description="Sep 1 2025">
  ### 🔀 Dualplex Assistant Mode (Beta)

  <Frame>
    <img alt="Image" />
  </Frame>

  We’re excited to introduce **Dualplex Mode**, our newest and most powerful assistant experience — combining the best of both worlds from **Speech-to-Speech** and **Pipeline** modes.

  ### What’s new in Dualplex Mode:

  * 🎤 **Speech-to-Speech Intelligence** Leverages the advanced **STT + LLM stack** from our Realtime models for natural, fluid conversations with ultra-low latency.
  * 🔊 **Premium Voice Output** Uses **ElevenLabs TTS**, bringing high-quality voices and voice cloning capabilities directly into the experience.
  * ⚡ **Best of Both Modes** Seamlessly blends the responsiveness of Speech-to-Speech with the flexibility and voice quality of Pipeline.

  ### Why it matters:

  Dualplex gives you the **most realistic AI voice interactions yet**, making conversations smoother, more human-like, and easier to integrate into production environments.

  ⚠️ **Note:** Dualplex is currently in **beta**. We’re gathering feedback and improving quickly — try it out now and let us know what you think!
</Update>

<Update label="v1.4.9" description="Aug 31 2025">
  ### 🗣️ GPT-5 Realtime Speech-to-Speech

  <Frame>
    <img alt="Image" />
  </Frame>

  We’ve rolled out major improvements to enhance speed and conversation quality across the platform:

  * 🗣️ **GPT-5 Realtime in Speech-to-Speech Mode** – Natural, fluid conversations with ultra-low latency for voice interactions.
  * ⚡ **GPT-5 Mini & Nano in Pipeline Mode** – Optimized for minimal reasoning effort, delivering faster response times and smoother call flows.
</Update>

<Update label="v1.4.8" description="Aug 14 2025">
  ### 🧠 Campaigns just got smarter

  We’ve added powerful new controls to help you get more out of your outbound campaigns, avoid wasted calls, and make sure every lead gets the attention it deserves.

  Here’s what’s new:

  ### **1. Campaign Call Status Options**

  You now have **three new controls** at the campaign level to fine-tune how your leads are called:

  * **Retry until goal completed** *Continue calling until the goal is achieved.* Perfect for situations where a lead answers but doesn’t complete the desired action (e.g., no appointment booked). Calls will continue until the selected **goal variable** is marked as true.
  * **Retry on voicemail** *Continue calling until a human answers (skip voicemails).* If a call hits voicemail, the lead won’t be marked as completed — the system will retry until someone picks up.
  * **Goal variable** *Variable that must be true to mark lead as completed.* Select from your variables which one determines a “completed” lead. If the variable is false, the lead will be retried instead of being marked as completed.

  ### **2. Update Lead Data/Status from Automation Platform or API**

  You can now **update lead details and statuses directly from your connected automation tools or API calls**.

  * Change lead status (e.g., “created” instead of “completed”) dynamically.
  * Push updated information into your campaigns without manual edits.

  ### **3. Ringing Timeout in Assistant Settings**

  A new **ringing timeout** option in the Assistant settings lets you control how long to wait for an answer before moving on.

  * For outbound campaigns, set it **lower** to avoid voicemail and save agent time.
  * For campaigns with slower-answering customers, increase it to give them more time to pick up.
</Update>

<Update label="v1.4.7" description="Aug 8 2025">
  ### 🚀 GPT-5 Integration

  <Frame>
    <img alt="Image" />
  </Frame>

  Experience the most advanced AI yet — faster, smarter, and more accurate responses now power your workflows. New paramters for adjusting reasoning effort will be added shortly. Right now the default value makes it very smart but slow.
</Update>

<Update label="v1.4.6" description="Aug 4 2025">
  ### 📞 DTMF Input Tool

  <Frame>
    <img alt="Image" />
  </Frame>

  Easily send keypad inputs during outbound calls, enabling smooth navigation through IVR menus and automated workflows.
</Update>

<Update label="v1.4.5" description="Jul 28 2025">
  ### 📋 Leads kanban board

  <Frame>
    <img alt="Image" />
  </Frame>

  Added **Kanban view** to the Leads section for a more visual workflow. You can now drag and drop leads between stages, quickly update statuses, and track progress at a glance.
</Update>

<Update label="v1.4.4" description="Jul 21 2025">
  ### 📚 Knowledgebase search & improved management

  <Frame>
    <img alt="Image" />
  </Frame>

  Knowledgebases have just been improved. Now you can:

  * Search within your knowledgebase documents
  * Delete an individual document. This is useful when you want to update a small part of an info without having to replace the whole knowledgebase
  * View all the ingested chunks in each document
</Update>

<Update label="v1.4.3" description="Jul 14 2025">
  ### 📲 Make phone call action in automation platform

  <Frame>
    <img alt="Image" />
  </Frame>

  Added a new *“Make Phone Call”* action that instantly dials a single number as soon as the API endpoint is invoked—no campaign setup required. Perfect for one-off or time-critical calls, while campaigns remain the recommended solution for bulk calling lists. You can find this action in the automation platform or API.
</Update>

<Update label="v1.4.2" description="Jul 1 2025">
  ### 👥 Secondary contacts on leads

  <Frame>
    <img alt="Image" />
  </Frame>

  You can now attach multiple backup contacts to every lead. When the primary contact doesn’t answer, calls automatically cascade to the next contact in the list. Add, reorder, or remove secondary contacts from the lead details panel for smoother outreach and higher connect rates.
</Update>

<Update label="v1.4.1" description="Jun 29 2025">
  ### 📶 Stable SIP proxy server

  Customers that used "Outbound SIP proxy server" for their outbound SIP trunk connections to come from a fixed IP, can now switch to the new stable server which offers better connection and stability as this feature was previously in beta. If you used this feature before the update, you will see a button to migrate to the new server from the SIP trunk interface. *Make sure to allow in your PBX/VoIP provider the new IP which you can find in the same SIP trunk interface dialog from phone numbers page.*
</Update>

<Update label="v1.4.0" description="June 16 2025">
  ### 🌍 Multi-lingual assistants

  <Frame>
    <img alt="Multi-lingual assistants configuration interface" title="Multi-lingual Assistants" />
  </Frame>

  Assistants can now speak multiple languages in the same conversation by setting up "secondary languages" in assistant settings first tab. They can switch language mid-call based on customer needs, providing seamless multilingual support.

  ### 🌐 Web widget - Voice AI for websites

  <Frame>
    <img alt="Web widget customization interface" title="Voice AI Web Widget" />
  </Frame>

  Embed assistants on websites with the voice AI widget similar to chatbots but with voice. You can fully customize the widget appearance from assistant settings from the "Web widget" button: `colors`, `texts`, `positions` and more. Paste the generated script tag snippet on any website page and you're good to go.
</Update>

<Update label="v1.3.14" description="May 26 2025">
  ### 🌟 Go High Level calendar integration

  <Frame>
    <img alt="Go High Level calendar integration interface" title="Go High Level calendar integration" />
  </Frame>

  Fetch available slots and book appointments using GoHighLevel calendars

  ### New Gemini 2.5-flash dialog model *(beta)*

  Added newest speech to speech model performing best for quality and latency. Includes 30+ voices and works in multi-lingual as well.

  ***

  ## 🖥️ Application

  ### Interface

  * **Added account level timezone setting**
  * Added minimum words interruption option in assistant settings
  * Added volume slider for background ambiance audio

  ### White label panel

  * Panel redesign
  * You can now create custom system prompts on your instance for your users to choose from
  * Integrate Google/LinkedIn social providers for login/register

  ***

  ## ⚙️ Automation Platform

  * **New action: Delete lead** - Delete leads programmatically
  * **New action: Start/Stop campaign** - Control campaign status programmatically
  * **Improved** - Automation platform loads 10x faster

  ***

  ## 🔗 API

  * **Delete lead** - New API endpoint to permanently delete leads
  * **Start/Stop campaign** - Control campaign status programmatically with new API endpoints
</Update>

<Update label="v1.3.13" description="May 1 2025">
  ### 🚀 New 2.0 Voice Engine - Speak Like Never Before

  <Frame>
    <img alt="New 2.0 Voice Engine interface" title="New 2.0 Voice Engine" />
  </Frame>

  The long awaited new engine has been deployed in the platform. It comes with improvements on overall conversation from response times, more emotion, better understanding to improved interruption handling and natural feel.

  ### ⚡ Real-time Speech-to-Speech Mode

  <Frame>
    <img alt="Real-time speech-to-speech mode interface" title="Real-time Speech-to-Speech Mode" />
  </Frame>

  Skip TTS round-trips and give callers instant, more natural replies. Experience unprecedented conversation flow with real-time processing.

  ### 🎭 Sentiment Aware Filler Audios

  <Frame>
    <img alt="Sentiment aware filler audios interface" title="Sentiment aware filler audios" />
  </Frame>

  Select different filler audios based on customer reply sentiment for even faster responses. Your AI assistant now adapts its tone and pace based on customer emotions.

  ***

  ## 📚 Knowledge Management

  ### Build a Living Knowledgebase in Minutes

  <Frame>
    <img alt="Living knowledgebase builder interface" title="Build a Living Knowledgebase" />
  </Frame>

  * **Point-and-scrape any website** — Product docs, help centers, wikis, or Notion pages
  * **Drag-and-drop PDFs & files** — We'll ingest the text automatically so your agents can use it in-call

  <Frame>
    <img alt="Living knowledgebase builder interface" title="Build a Living Knowledgebase" />
  </Frame>

  ***

  ## 🖥️ Application

  ### Call directly from your browser *(beta)*

  <img alt="Browser calling interface" title="Call directly from your browser" />

  This feature is present in beta mode and you can test it from assistant settings. It will soon be extended as a widget that can be embedded on websites.

  ### Multi number call transfer

  <img alt="Multi number call transfer interface" title="Multi number call transfer" />

  You can now route calls to multiple destination phone numbers like different people or departments according to your flow.
</Update>


# Data Retention
Source: https://docs.autocalls.ai/settings/data-retention

Configure GDPR-compliant data retention periods for your account

Data retention settings let you control how long different types of data are stored in your account. This helps you stay compliant with GDPR and other data protection regulations.

## Overview

You can configure retention periods for four resource types, each independently adjustable between 1 and 24 months. Data older than the configured retention period is automatically removed on a recurring schedule — no manual action needed.

## Resource Types

| Resource         | Description                               | Default   |
| ---------------- | ----------------------------------------- | --------- |
| **Calls**        | Call records, transcripts, and recordings | 24 months |
| **Leads**        | Lead records within campaigns             | 24 months |
| **Chat History** | WhatsApp and web widget conversations     | 24 months |
| **SMS**          | SMS message records                       | 24 months |

## Configuring Retention

1. Navigate to your **Profile** settings
2. Find the **Data Retention** section (alongside timezone settings)
3. Set your preferred retention period for each resource type (1-24 months)
4. Save your changes

## How It Works

* **Automatic cleanup**: A scheduled process removes data older than your configured retention period
* **Soft deletion**: Records are soft-deleted, not permanently destroyed immediately
* **Per-resource control**: Each resource type has its own independent retention period

## Best Practices

* **Review local regulations**: Different regions may require specific retention periods (e.g., GDPR recommends keeping data only as long as necessary)
* **Start with defaults**: The 24-month default provides a good balance for most use cases
* **Shorten for sensitive data**: If you handle sensitive customer information, consider shorter retention periods


# AI Behavior Issues
Source: https://docs.autocalls.ai/troubleshooting/ai-behavior

Troubleshoot and optimize your AI assistant's conversation behavior and responses

Your AI's behavior can be fine-tuned through a combination of engine settings and prompt adjustments.

## Engine Settings Impact

Different AI engine modes affect behavior:

### Fast Engine

* Quick, more conversational responses
* May occasionally miss context
* Best for: Simple interactions, sales calls
* Works great with Filler Audio for natural flow

### Standard Engine

* Balanced understanding and speed
* Good for most use cases
* Default recommendation for new assistants

### Accurate Engine

* Deep context understanding
* More thoughtful responses
* Best for: Complex support, detailed information gathering
* May have longer pauses between responses

## Common Issues & Solutions

1. **AI Misunderstanding Context**

   * Switch to Accurate Engine
   * Add more context to your prompt
   * Include example conversations

2. **Unnatural Conversation Flow**

   * Enable Filler Audio for smoother transitions
   * Use Fast Engine for quicker back-and-forth
   * Add conversation examples in your prompt

3. **Repetitive Responses**
   * Review and update your system prompt
   * Add variation examples
   * Consider switching to Standard/Accurate engine

## Optimization Tips

* **Sales Calls**: Fast Engine + Filler Audio for engagement
* **Customer Support**: Accurate Engine for better problem solving
* **Lead Qualification**: Standard Engine for balanced performance

## Testing Changes

After adjusting settings:

1. Use the test call feature
2. Try different conversation scenarios
3. Monitor call recordings for improvement

***

**Tip:** Start with Standard Engine and adjust based on your specific needs and feedback.


# Billing & Credits
Source: https://docs.autocalls.ai/troubleshooting/billing

Troubleshoot billing issues, understand charges, and learn about refund policies and usage tracking

## 1. Unexpected Charges?

* **Large Outbound Campaign?** Possibly your calls used more minutes than expected.
* **Did You Rent Multiple Numbers?** Monthly fees stack if you keep multiple lines active.

## 2. Refund / Cancellation Policies

* Check your plan's terms. Usually usage-based minutes are non-refundable because resources are used in real-time.
* If you have a monthly plan with included minutes, you can often cancel future renewals but not partial months.

## 3. Tracking Usage

* **Dashboard**: Real-time usage counters show minutes consumed.
* **Notifications**: Set alerts if you near a monthly threshold.

***

**Tip:** If usage spiked unexpectedly, see call logs or see if an employee triggered a large campaign by mistake.


# Cal.com Issues
Source: https://docs.autocalls.ai/troubleshooting/cal-com

Troubleshoot common Cal.com integration issues

Solutions for common Cal.com integration problems.

## Connection Issues

### Invalid API Key

**Problem:** Events not loading or sync fails

**Solution:**

* Verify API key is active in Cal.com → Settings → Developer → API Keys
* Ensure key includes `cal_live_` prefix
* Generate a new API key if needed

### Events Not Loading

**Problem:** Event dropdown is empty after entering API key

**Solution:**

* Check API key is correct
* Click outside the API key field to trigger event loading
* Refresh the page if events still don't appear
* Verify you have events created in Cal.com

## Sync Issues

### Sync Event Failed

**Problem:** "Sync Event" button fails or shows error

**Solution:**

1. Click **"Troubleshoot"** button instead
2. This resets all booking fields to correct configuration
3. Verify changes in Cal.com event settings

### Field Configuration Errors

**Problem:** Getting errors about required fields or missing fields

**Solution:**

* Click **"Troubleshoot"** to reset fields
* Only name, email, phone should be required
* All other fields (location, guests, etc.) should be optional

## Booking Failures

### No Calendar Invites Sent

**Problem:** Bookings succeed but customer doesn't receive invite

**Solution:**

* Define `email` variable in [assistant settings](/ai-assistants/settings/prompt-and-tools#call-variables)
* Pass customer email when creating leads
* Verify email format is valid

### Phone Number Missing

**Problem:** Phone number doesn't appear in calendar events

**Solution:**

* Click **"Sync Event"** or **"Troubleshoot"** button
* This automatically adds the phone field to the event
* Phone number is included after sync

### Booking Time Zone Issues

**Problem:** Appointments scheduled at wrong time

**Solution:**

* Check time zone in Cal.com event settings
* Verify assistant is getting correct time from customer
* Test with specific time mentions during call

## Testing Issues

### Web Call Bookings Fail

**Problem:** Bookings work inconsistently with web calls

**Solution:**

* Use real phone calls for testing (not web calls)
* Web calls may not pass phone variable correctly
* When using web calls, provide phone in international format with + prefix (e.g., "+1 555-123-4567")
* Phone calls ensure all variables are transmitted correctly

### Multiple Calendars Not Working

**Problem:** Only one calendar works or events conflict

**Solution:**

* Each calendar should have different event selected
* Use distinct event names (e.g., "15min", "30min")
* Sync each event separately after adding

## Getting Help

If issues persist:

1. Check call transcripts for booking attempts
2. Verify Cal.com event shows in Cal.com dashboard
3. Test with simple phone call booking
4. Contact support with:
   * Error message screenshot
   * Cal.com event settings screenshot
   * Call transcript showing booking attempt


# Calendly Issues
Source: https://docs.autocalls.ai/troubleshooting/calendly

Troubleshoot common Calendly integration issues

Solutions for common Calendly integration problems.

## Connection Issues

### OAuth Authorization Fails

**Problem:** Unable to connect Calendly account

**Solution:**

* Try connecting in an incognito/private browser window
* Verify you have admin access to your Calendly account
* Check that third-party app permissions are enabled in Calendly

### Events Not Loading

**Problem:** Event dropdown is empty after connecting

**Solution:**

* Click **"Load Events"** button to fetch event types
* Wait for the sync to complete (may take a few seconds)
* Refresh the page if events still don't appear
* Verify you have active event types in your Calendly account

## Booking Failures

### Location Kind Error

**Problem:** "Failed to book appointment: Specified location kind is not configured for this event type"

**Cause:** Your Calendly event type has a location setting (e.g., Google Meet, Zoom) that doesn't match what the voice agent uses when booking.

**Solution:**

1. Log in to your Calendly account at [calendly.com](https://calendly.com)
2. Go to **Event Types** and click on the event type linked to your assistant
3. Click **Edit** on that event type
4. Scroll to the **Location** section
5. Change the location to one of these options:
   * **"Custom"** — this is the safest option and works in all cases
   * **"Phone Call" → "Inbound call"** — also works well for voice AI use cases
   * If you have multiple locations, make sure **"Custom"** is included as one of the options
6. **Save** the event type
7. Try booking again through the assistant

<Warning>
  If your event type is set to a video conferencing location only (Google Meet, Zoom, Microsoft Teams), bookings will fail because the voice agent doesn't generate meeting links. Either switch to "Custom" or add "Custom" as an additional location option.
</Warning>

### Booking Time Zone Issues

**Problem:** Appointments scheduled at wrong time

**Solution:**

* Check the time zone in your Calendly event settings
* Verify the assistant's time zone is configured correctly
* Test with specific time mentions during a call

## Testing Issues

### Web Call Bookings Fail

**Problem:** Bookings work inconsistently with web calls

**Solution:**

* Use real phone calls for testing (not web calls)
* Web calls may not pass the phone variable correctly
* When using web calls, provide the phone number in international format with + prefix (e.g., "+1 555-123-4567")

## Getting Help

If issues persist:

1. Check call transcripts for booking attempts
2. Verify the event type shows correctly in your Calendly dashboard
3. Test with a simple phone call booking
4. Contact support with:
   * Error message screenshot
   * Calendly event type settings screenshot (especially the Location section)
   * Call transcript showing the booking attempt


# Call Quality Issues
Source: https://docs.autocalls.ai/troubleshooting/call-quality

Troubleshoot and optimize call quality, latency, and connection issues

Call quality can be affected by both technical factors and AI settings. Here's how to optimize both:

## AI Engine Impact

Your choice of AI engine affects perceived call quality:

### Fast Engine + Filler Audio

* Minimal latency
* Quick back-and-forth
* Natural conversation flow
* Best for most calls

### Standard/Accurate Engine

* Longer processing time
* More accurate responses
* Better for complex conversations

## Optimization Tips

* Start with Fast Engine + Filler Audio
* Switch to Standard/Accurate only if needed
* Monitor call recordings for quality
* Test different voice models

## Quick Fixes

If experiencing issues:

1. Try a test call
2. Switch to a faster engine setting
3. Enable filler audio
4. Check network connection

***

**Tip:** The combination of Fast Engine and Filler Audio typically provides the best perceived call quality.


# Campaign Issues
Source: https://docs.autocalls.ai/troubleshooting/campaigns

Solve common campaign issues and optimize performance

Quick solutions for common campaign problems and performance optimization tips.

## Campaign Won't Start

### Phone Number Not Configured

**Error:** "Your agent does not have a phone number setup"

**Solution:**

1. Go to your [Assistant Settings](/ai-assistants/settings/general#phone-number-configuration)
2. Configure a phone number (Platform number, SIP, or Caller ID)
3. Save assistant settings
4. Try starting campaign again

### Insufficient Balance

**Error:** "Insufficient balance to start the campaign"

**Solution:**

1. Check your account balance in billing section
2. Add funds to your account
3. Return to campaign and click start

### No Leads to Call

**Error:** "No leads to call"

**Solution:**

1. Add leads manually or import from CSV
2. Verify leads have valid phone numbers
3. Check that leads aren't all marked as completed
4. Ensure "Mark complete when no leads" setting matches your needs

## No Calls / Messages Being Sent

### Outside Allowed Hours / Schedule Windows

**Issue:** Campaign shows as running but nothing is dialing or sending

**Check:**

* Current time is inside at least one **schedule window** (or legacy start/end)
* Overnight windows: if end is earlier than start (e.g. 16:00→02:00), midday is *outside* the window
* Today is an allowed day
* Campaign timezone matches the schedule you expect

**Solution:** Adjust schedule windows or wait until the next allowed interval

### WhatsApp Campaign Not Sending

**Check:**

* Sender and template are still approved and owned by your account
* Chat credits / balance are sufficient
* Template variable mapping has values for every lead (blank mapped values block sends)
* You have not hit the **user-wide pool of 10** in-flight WhatsApp campaign sends (multiple WhatsApp campaigns share this pool)

**Solution:** Top up chat credits, fix mapping, or wait for in-flight sends to finish

### SMS Campaign Won't Start

SMS campaigns may be temporarily disabled on the platform. If start fails with an unavailable-channel message, use WhatsApp or call campaigns until SMS is re-enabled.

### All Leads Called

**Issue:** Campaign appears idle

**Check:**

* All primary leads have been attempted maximum times
* Secondary contacts have been tried
* Goal completion status if using goal-based retry

**Solution:** Add more leads or review retry settings

## Call Quality Issues

### High Failure Rate

**Symptoms:** Many calls marked as "Failed"

**Common causes:**

* Invalid phone numbers in lead list
* Network connectivity issues
* Carrier restrictions

**Solutions:**

1. **Clean lead data:** Remove invalid numbers
2. **Test single calls:** Try calling individual leads manually
3. **Check number format:** Ensure proper formatting (+1234567890)
4. **Contact support:** For persistent technical issues

### Low Answer Rate

**Symptoms:** Most calls go to voicemail or unanswered

**Optimization:**

1. **Adjust calling hours:** Try different time windows
2. **Review retry interval:** Space out attempts more
3. **Check lead quality:** Verify numbers are current
4. **Caller ID setup:** Ensure professional caller ID display

## Retry Logic Problems

### Too Many Retries

**Issue:** Leads complaining about excessive calls

**Solutions:**

1. **Reduce max retries:** Lower from 5 to 2-3 attempts
2. **Increase retry interval:** Space calls 2-4 hours apart
3. **Disable voicemail retry:** Accept voicemail as contact
4. **Review goal variables:** Ensure proper completion tracking

### Not Enough Retries

**Issue:** Missing potential contacts with limited attempts

**Solutions:**

1. **Increase max retries:** Up to 5 attempts
2. **Enable voicemail retry:** Continue until human contact
3. **Adjust retry interval:** Try different times of day
4. **Use goal-based retry:** For high-value prospects

## Goal Completion Issues

### Goal Variable Not Working

**Issue:** Retry until goal completed not functioning

**Requirements:**

1. **Post-call variables** must be configured in assistant
2. **Boolean variable** must exist in post-call schema
3. **Variable name** must match exactly in campaign settings
4. **AI extraction** must be working properly

**Solution:** Test assistant's post-call variable extraction with manual calls

### False Goal Completion

**Issue:** Leads marked complete incorrectly

**Debugging:**

1. **Review call transcripts** for AI extraction errors
2. **Test variable definitions** with sample calls
3. **Adjust AI prompt** for clearer goal criteria
4. **Refine variable descriptions** in assistant settings

## Performance Optimization

### Slow Campaign Progress

**Causes:**

* Conservative retry intervals
* Limited allowed calling hours
* High failure rate reducing available leads

**Solutions:**

1. **Parallel processing:** Create multiple smaller campaigns
2. **Optimize timing:** Use peak answer hours
3. **Clean data:** Remove problematic numbers
4. **Increase calling window:** Extend allowed hours

### System Resource Issues

**Symptoms:** Delayed calls, processing bottlenecks

**Solutions:**

1. **Reduce concurrent campaigns:** Limit active campaigns
2. **Stagger campaign starts:** Don't start multiple campaigns simultaneously
3. **Contact support:** For platform performance issues

## Lead Management Issues

### Duplicate Contacts

**Issue:** Same person called multiple times from different leads

**Prevention:**

1. **Data cleanup:** Remove duplicates before import
2. **Phone number validation:** Check for format variations
3. **Lead deduplication:** Use tools to identify duplicates

### Secondary Contact Confusion

**Issue:** Unclear which contact was reached

**Solution:**

1. **Clear naming:** Use descriptive names for secondary contacts
2. **Call notes:** Review transcripts to identify who answered
3. **Lead organization:** Group related contacts properly

## Common Error Messages

### "Campaign is already in progress"

**Solution:** Campaign is already running. Pause it first to make changes.

### "Campaign is not running"

**Solution:** Campaign is paused or stopped. Start it to resume calling.

### "Assistant timezone not set"

**Solution:** Configure timezone in assistant settings before creating campaign.

## Getting Help

### Before Contacting Support

1. **Check error messages** for specific guidance
2. **Review campaign settings** for obvious issues
3. **Test with single lead** to isolate problems
4. **Check account status** and billing

### Information to Provide

* Campaign ID and name
* Error messages received
* Steps taken before issue occurred
* Expected vs actual behavior
* Assistant and phone number configuration

<Warning>
  **Campaign delays:** Allow 10-15 minutes after starting before expecting calls to begin. The system needs time to initialize and queue leads.
</Warning>

<Note>
  For additional help with campaign optimization, see [Campaign Best Practices](/campaigns/creating-campaigns).
</Note>


# GoHighLevel Issues
Source: https://docs.autocalls.ai/troubleshooting/gohighlevel

Common GoHighLevel integration problems and solutions

This page covers common issues when using GoHighLevel integrations with Autocalls.ai.

## Appointment Scheduling Issues

### Missing API Key Error

**Problem:** Getting error "missing api\_key location\_id or calendar\_id for GoHighLevel"

**Solution:**

1. Go to [assistant settings](/ai-assistants/settings/prompt-and-tools#default-tools)
2. Navigate to **Appointment Scheduling** section
3. Click **Disconnect** to remove current GoHighLevel connection
4. Click **Connect** again to re-authorize
5. **Select an calendar** from the dropdown
6. **Click Save** to apply the configuration
7. **Verify** the connection shows as active after reconnecting

### Connection Problems

**OAuth Authorization Fails:**

* **Try incognito mode** to resolve authentication conflicts
* **Verify account selection** - ensure you selected the correct GoHighLevel account
* **Check permissions** - confirm you have admin access to the GoHighLevel account

### Calendar Not Appearing

**Calendars don't show in assistant settings:**

* **Refresh connection** by disconnecting and reconnecting
* **Verify calendar setup** in your GoHighLevel account
* **Check account permissions** for calendar access

### Booking Failures

**Appointments not being scheduled:**

* **Email Required:** Ensure the assistant has an email defined in [assistant settings](/ai-assistants/settings/prompt-and-tools#default-tools) and the lead has an email in inbound variables or from conversation. See [Email Requirement for Appointments](/ai-assistants/gohighlevel-scheduling#email-requirement-for-appointments) for detailed setup.
* **Test calendar availability** - verify the calendar has open slots
* **Check time zones** - ensure correct time zone configuration in both systems
* **Review assistant logs** - check call transcripts for booking attempts
* **Verify calendar settings** in GoHighLevel for booking restrictions

### Data Mapping Problems

**Lead data not syncing correctly:**

* **Verify field mapping** in automation platform
* **Check required fields** in GoHighLevel
* **Test with sample data** before live campaigns

## Getting Help

If these solutions don't resolve your issue:

1. **Check call transcripts** to see exactly what the AI attempted
2. **Test the integration** with a simple appointment booking
3. **Contact support** with specific error messages and screenshots

**Common Support Information Needed:**

* Screenshot of the error message
* Calendar configuration details
* Assistant settings configuration


# Leads Issues
Source: https://docs.autocalls.ai/troubleshooting/leads

Solve common lead management issues and import problems

Quick solutions for common lead management problems and import issues.

## Lead Import Issues

### Import Fails Completely

**Error:** "Import failed" or "File format not supported"

**Solutions:**

1. **Check file format:** Use CSV or Excel files only
2. **Verify campaign selection:** Ensure a campaign is selected for import
3. **File size limits:** Keep files under 10MB for optimal performance
4. **Encoding issues:** Save CSV with UTF-8 encoding

### No Leads Imported

**Issue:** Import completes but no leads appear

**Solutions:**

1. **Column mapping:** Verify you mapped the phone number column during import
2. **Data validation:** Check that phone numbers are in correct format
3. **Empty rows:** Remove empty rows from file
4. **Required fields:** Ensure phone number column contains valid data
5. **File headers:** Ensure your CSV/Excel has a header row (any names work)

### Partial Import Success

**Issue:** Some leads imported, others failed

**Solutions:**

1. **Download error report:** Check failed rows for specific issues
2. **Phone number format:** Ensure international format (+1234567890)
3. **Duplicate detection:** Remove duplicate phone numbers
4. **Invalid data:** Fix malformed phone numbers or missing required data

### Processing Delays

**Issue:** Import shows as processing for extended time

**Explanation:**

* Large files are processed in background
* Processing time increases with file size
* System queues multiple imports

**Solutions:**

1. **Wait for completion:** Check notifications for updates
2. **Break up large files:** Split into smaller batches (500-1000 leads)
3. **Contact support:** If processing exceeds 30 minutes

## Lead Management Issues

### Lead Not Appearing in Campaign

**Issue:** Imported lead doesn't show in campaign

**Check:**

* Lead status (should be "Created" or "Scheduled")
* Campaign filters or search settings
* Lead marked as completed accidentally

**Solutions:**

1. **Reset lead status:** Change status to "Created" to re-queue
2. **Verify campaign assignment:** Check lead is assigned to correct campaign
3. **Refresh interface:** Reload campaign page

### Invalid Phone Numbers

**Issue:** Phone numbers rejected during import

**Common formats:**

* **Correct:** +1234567890 (international format)
* **Incorrect:** (123) 456-7890, 123-456-7890, 1234567890

**Solutions:**

1. **Standardize format:** Convert all numbers to +1234567890 format
2. **Remove formatting:** Strip spaces, parentheses, dashes
3. **Country codes:** Add appropriate country code prefix
4. **Validation tools:** Use phone validation before import

### Duplicate Leads

**Issue:** Same person appears multiple times

**Prevention:**

1. **Data cleanup:** Remove duplicates before import
2. **Phone validation:** Check for format variations of same number
3. **Name matching:** Identify potential duplicates by name + phone
4. **Lead deduplication:** Use tools to identify similar entries

### Secondary Contacts Not Working

**Issue:** Secondary contacts not being called

**Requirements:**

* Secondary contact must have valid phone number
* Primary contact must reach max retries first
* Campaign must be configured for secondary contacts

**Solutions:**

1. **Verify setup:** Check secondary contact configuration
2. **Lead status:** Ensure primary contact has been attempted
3. **Campaign settings:** Confirm secondary contact calling is enabled

## Variable and Data Issues

### Variable Mapping Errors

**Issue:** Custom variables not importing correctly

**Solutions:**

1. **Column mapping:** Ensure you correctly mapped each variable to its column during import
2. **Auto-detection:** System auto-detects mappings based on common column names
3. **Data types:** Ensure data matches expected variable types
4. **Required variables:** Map all variables defined in [assistant configuration](/ai-assistants/settings/prompt-and-tools#call-variables)
5. **Default values:** Unmapped variables will use assistant's default values

### Missing Lead Information

**Issue:** Leads missing names, emails, or custom data

**Solutions:**

1. **Column mapping:** Verify all columns are mapped correctly
2. **Optional fields:** Confirm optional fields are included in import
3. **Data validation:** Check source data for completeness
4. **Re-import:** Add missing data and re-import if needed

## Campaign Integration Issues

### Lead Status Problems

**Issue:** Leads stuck in wrong status

**Status meanings:**

* **Created:** Ready to be called
* **Scheduled:** Queued for next attempt
* **Processing:** Currently being called
* **Completed:** Finished or goal achieved
* **Max Retries:** Reached retry limit

**Solutions:**

1. **Manual status change:** Update status in leads table
2. **Campaign restart:** Pause and restart campaign if needed
3. **Retry settings:** Adjust max retries or intervals

### Variable Inheritance Issues

**Issue:** Lead variables not working in calls

**Solutions:**

1. **Assistant setup:** Verify variables defined in [assistant settings](/ai-assistants/settings/prompt-and-tools#call-variables)
2. **Variable names:** Ensure exact match between lead data and assistant variables
3. **Data format:** Check variable data is in expected format
4. **Test calls:** Use manual test calls to verify variable passing

## File Format Issues

### CSV Problems

**Common issues:**

* Wrong delimiter (use comma, not semicolon)
* Missing headers in first row
* Quoted fields with unescaped quotes
* Mixed encoding (use UTF-8)

**Solutions:**

1. **Standard format:** Use comma-separated values
2. **Headers required:** First row must contain column names
3. **Text qualification:** Use double quotes for text fields
4. **Encoding:** Save as UTF-8 encoded CSV

### Excel Problems

**Common issues:**

* Multiple sheets (only first sheet imported)
* Merged cells causing data misalignment
* Formulas instead of values
* Hidden characters or formatting

**Solutions:**

1. **Single sheet:** Use only first worksheet
2. **Unmerge cells:** Separate merged cells
3. **Values only:** Convert formulas to values
4. **Clean format:** Remove special formatting

## Getting Help

### Before Contacting Support

1. **Download error report:** Review specific error messages
2. **Check file format:** Verify CSV/Excel format compliance
3. **Test small batch:** Try importing 5-10 leads first
4. **Review documentation:** Check import requirements

### Information to Provide

* Error messages received
* Sample of import file (with sensitive data removed)
* Campaign settings and requirements
* Expected vs actual behavior
* Assistant variable configuration

<Warning>
  **Data privacy:** Remove sensitive information from sample files before sharing with support.
</Warning>

<Note>
  For lead management best practices, see [Managing Leads](/leads/managing-leads) and [Campaign Setup](/campaigns/creating-campaigns).
</Note>


# SIP Integration Issues
Source: https://docs.autocalls.ai/troubleshooting/sip-integration

Troubleshoot SIP trunk connection problems and configuration issues

This guide helps resolve common SIP integration issues when connecting your SIP provider to Autocalls.ai.

## Testing Strategy

1. **Test Outbound calls first** - easier to configure
2. **Test Inbound calls second** - after outbound works

## Outbound SIP Issues

### Connection Problems

**SIP trunk not connecting for outbound calls:**

1. **Verify SIP Credentials** - username, password, server details
2. **Phone Type Selection** - check with provider for correct type
3. **Fixed IP Configuration** - usually enable and enter provider's IP address
4. **Provider Settings** - verify codec, transport, port settings

### SIP Registration Issues

**Important:** Autocalls.ai platform:

* **Does NOT send SIP REGISTER** messages to your provider
* **Does NOT require receiving SIP REGISTER** from your provider
* Uses **direct call authentication** instead

### Testing Outbound

1. Configure SIP trunk settings
2. **Make a direct test call** through platform
3. Check call logs for errors

## Inbound SIP Issues

### Authentication Setup

**For inbound calls:**

1. **Use IP Authentication** - instead of username/password
2. **Whitelist Provider IPs** - add ALL provider IPs in our platform
3. **Provider Configuration - IMPORTANT**
   * **Use our FQDN domain** for routing (NOT the outbound IP)
   * **Send to domain** - ensures correct routing
   * **Do NOT send to IP** - causes routing issues

### Common Inbound Issues

**Calls not reaching assistant:**

* Verify all provider IPs whitelisted
* Ensure provider sends to FQDN domain (not IP)
* Check destination number format

## General Issues

**Network problems:**

* Check internet connectivity
* Verify no firewall blocking SIP traffic

**Provider compatibility:**

* Verify provider supports direct calling (no registration)
* Check IP authentication support

## Testing Checklist

### Before Contacting Support

1. **Outbound Test:**
   * [ ] Credentials verified
   * [ ] Phone type selected correctly
   * [ ] Fixed IP enabled with provider's IP address
   * [ ] Direct test call attempted

2. **Inbound Test:**
   * [ ] IP authentication configured
   * [ ] All provider IPs whitelisted in our platform
   * [ ] Provider configured to send to FQDN domain (not direct IP)
   * [ ] Test call from external number

3. **General:**
   * [ ] Network connectivity verified

## FAQ

### Transfer Phone Call Not Working

**Q: Why is the Transfer Phone Call function not working?**

**A:** If call transfers are failing, try these solutions:

1. **Check SIP Transfer Settings:**
   * Set transfer call to "Advanced" mode
   * Use SIP URI format: `sip:number@sip-server`
   * Example: `sip:+1234567890@sip.provider.com:5060`

2. **Verify Provider Support:**
   * Confirm your SIP provider supports SIP REFER
   * Check if transfer functionality is enabled on your account
   * Some providers require specific configuration for transfers

3. **Test Different Formats:**
   * Try with port: `sip:+1234567890@sip-server:5060`
   * Try without port: `sip:+1234567890@sip-server`
   * Try simple format: `sip:+1234567890`

4. **Verify Destination:**
   * Ensure the target number is reachable
   * Test if the number answers calls normally
   * Check if the number is blocked or restricted

5. **Common Issues:**
   * Provider doesn't support SIP REFER
   * Incorrect SIP URI format
   * Network/firewall blocking transfer requests
   * Destination number not answering

**Troubleshooting steps:**

1. Test with a known working number first
2. Try different SIP URI formats
3. Contact your SIP provider to confirm transfer support
4. Check call logs for specific error messages

## Getting Help

**When contacting support, provide:**

* Error messages from call logs
* SIP trunk configuration
* Test results (outbound and inbound)
* Transfer attempt details and SIP URI format used


# Voice & Response Issues
Source: https://docs.autocalls.ai/troubleshooting/voice-problems

Troubleshoot voice quality and response timing issues with your AI assistant

If you're experiencing issues with voice quality or response timing, you can adjust several settings to optimize performance.

## Response Speed vs. Accuracy

Your AI assistant has adjustable engine settings:

* **Fast Engine**: Quicker responses but might be less accurate
* **Standard Engine**: Balanced speed and accuracy
* **Accurate Engine**: Most accurate but slower responses

Adjust these in your assistant's settings under "AI Engine Configuration".

## Filler Audio

To minimize silence during processing:

* Enable "Filler Audio" in your [assistant settings](/ai-assistants/settings/general#audio-enhancement-settings)
* The AI will use natural sounds (like "hmm" or "one moment") while processing
* Works best with the Fast Engine for near-instant perceived responses

## Common Issues & Solutions

1. **Slow Responses**

   * Switch to Fast Engine mode
   * Enable Filler Audio
   * Simplify your system prompt

2. **Inaccurate Responses**

   * Use the Accurate Engine mode
   * Provide more context in your prompt
   * Add specific examples

3. **Voice Quality**
   * Try different voice models
   * Adjust speech speed settings
   * Try cloning a voice

4. **Assistant Not Responding or Missing Speech in Transcript**
   * **Disable noise cancellation** in your [assistant settings](/ai-assistants/settings/general#audio-enhancement-settings)
   * Noise cancellation can sometimes filter out speech or cause the assistant to not respond
   * Test with noise cancellation disabled to see if speech is properly detected

## Optimization Tips

* For sales calls: Use Fast Engine + Filler Audio for natural flow
* For support: Consider Accurate Engine for better comprehension

***

**Need help?** Contact support if these adjustments don't resolve your issues.


# Web Widget Issues
Source: https://docs.autocalls.ai/troubleshooting/web-widget

Troubleshoot common web widget problems and integration issues

Solutions for common web widget issues.

## Widget Not Appearing

**Check these:**

* Embed code placed before closing `</body>` tag
* Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
* Test in incognito window
* Verify plan includes web widget access
* Check browser console (F12) for JavaScript errors
* Re-copy embed code from widget configuration

## Voice Not Working

**HTTPS Required:**
Voice functionality requires HTTPS. HTTP sites can only use chat mode.

**Check these:**

* Website uses HTTPS (SSL certificate)
* Browser has microphone permission
* Microphone works in other applications
* Using modern browser (Chrome, Firefox, Safari, Edge)
* No VPN or firewall blocking WebRTC

## Chat Not Working

**Check these:**

* Browser console (F12) for errors
* Assistant is properly configured
* Test assistant with [Test Chat](/ai-assistants/test-chat)
* Review conversation in [Conversations](/conversations/overview) page
* Reload page to reset widget state

## Chat history resets on refresh

Chat history should persist across page reloads in the same browser. If it does not:

* Confirm the widget is in **Chat** or **Voice & Chat** mode (voice-only sessions do not persist)
* Check that the browser allows localStorage for the widget origin
* If you pass `data-customer-identifier` / `data-variables`, a page refresh should still reopen the same chat — identity injection does not start a new conversation by itself
* To start a fresh chat on purpose, use the widget refresh button or call `window.AIChatWidget.reset('your-assistant-id')`

## Pre-Chat Form Issues

**Check these:**

* Form fields configured in widget settings
* Form fields have both name and label
* Widget settings were saved
* Field names match assistant variables exactly
* Clear browser cache and test in incognito
* If you inject `data-variables`, the form is skipped only when **every required field** already has a value. Missing required keys still show the form, pre-filled with the values you passed
* After logout, call `window.AIChatWidget.reset('your-assistant-id')` and stop injecting identity attributes, otherwise the previous visitor's form data stays in the browser

## Display & Styling Issues

**Check these:**

* Widget position setting in configuration
* Website CSS might override widget styles
* Change primary color for better visibility
* Check if page elements cover the widget (z-index)
* Test on actual mobile devices

## Configuration Not Updating

**Check these:**

* Click "Save widget settings" button
* Copy fresh embed code after saving
* Replace old embed code on your website
* Clear browser cache (Ctrl+Shift+R)
* Test in incognito window

## WordPress/CMS Issues

**Check these:**

* Use Custom HTML block/widget (not visual editor)
* Add embed code before closing `</body>` tag
* Clear caching plugin cache
* Temporarily disable security plugins if needed

## Still Having Issues?

1. Check browser console (F12) for errors
2. Test in incognito mode
3. Try different browser
4. Test assistant with [Test Chat](/ai-assistants/test-chat)
5. Contact support with browser console screenshot

## Related Documentation

* [Web Widget Setup](/ai-assistants/web-widget)
* [Test Chat Interface](/ai-assistants/test-chat)
* [Viewing Conversations](/conversations/viewing-and-managing)


# WhatsApp Troubleshooting
Source: https://docs.autocalls.ai/troubleshooting/whatsapp

Common issues and solutions for WhatsApp Business integration

## Sender Issues

### Sender Stuck in "Creating" or "Pending" Status

**Symptoms:**

* Sender status shows "Creating" for more than a few minutes
* Sender stuck on "Pending" after completing Meta signup

**Solutions:**

1. **Complete the Meta signup flow**
   * Make sure you finished all steps in the Facebook popup
   * You should have seen a confirmation before being redirected back

2. **Check that you created a NEW account**
   * You must create a new WhatsApp Business Account during signup
   * Selecting an existing account will cause the integration to fail

3. **Verify phone number selection**
   * Did you click "Add new number" in the Meta popup?
   * Did you select the correct pre-verified number?

4. **Wait and refresh**
   * Sometimes setup takes a few minutes to complete
   * Refresh the page after 5 minutes

5. **Contact support**
   * If the issue persists for more than 30 minutes, contact support

### Verification Failed

**Symptoms:**

* Verification process fails
* Error message about verification timeout

**Solutions:**

1. **Wait before retrying**
   * Meta may temporarily rate-limit verification requests
   * Wait 5-10 minutes before trying again

2. **Try a different number**
   * Some numbers may have issues with Meta's verification
   * Try using a different phone number

3. **Check number type**
   * Only "normal" type numbers can be used for WhatsApp
   * SIP or special numbers are not supported

### Sender Shows "Offline"

**Symptoms:**

* Sender was working but now shows "Offline"
* Cannot send or receive messages

**Solutions:**

1. **Check for policy violations**
   * Review any emails from Meta about policy issues
   * High block rates or spam reports can cause offline status

2. **Check quality rating**
   * Low quality rating can trigger offline status
   * Review your messaging practices

3. **Re-authenticate**
   * Sometimes the connection needs to be refreshed
   * Contact support for assistance

### Sender Suspended

**Symptoms:**

* Sender status shows "Suspended"
* Error mentions policy violation

**Solutions:**

1. **Review suspension reason**
   * Check the error message for specific details
   * Common reasons: spam reports, prohibited content, high block rates

2. **Address the issue**
   * Stop any problematic messaging campaigns
   * Review Meta's commerce policies

3. **Appeal the suspension**
   * Contact Meta support through Facebook Business Manager
   * Provide evidence of compliance

## Template Issues

### Template Rejected

**Symptoms:**

* Template status shows "Rejected"
* Rejection reason displayed

**Common Rejection Reasons & Solutions:**

| Reason                         | Solution                            |
| ------------------------------ | ----------------------------------- |
| Promotional content in Utility | Change category to Marketing        |
| Missing variable samples       | Add clear, realistic sample values  |
| URL shorteners                 | Use full, branded URLs              |
| Aggressive language            | Soften tone, remove threats         |
| Wrong category                 | Select correct category for content |

### Template Stuck in "Pending"

**Symptoms:**

* Template has been pending for more than 24 hours

**Solutions:**

1. **Wait for review**
   * Marketing templates can take up to 48 hours
   * Complex templates may take longer

2. **Check for issues**
   * Review template content for potential policy issues
   * Ensure sample values are clear and appropriate

3. **Create an alternative**
   * If urgent, create a new template with different name
   * Use simpler content that's more likely to be approved

### Template Disabled

**Symptoms:**

* Previously approved template now shows "Disabled"

**Causes:**

* Low quality score from customer feedback
* Template received too many blocks or reports

**Solutions:**

1. **Review usage patterns**
   * Were you sending to customers who didn't expect messages?
   * Was the content relevant to recipients?

2. **Create a new version**
   * Create a new template with improved content
   * Consider more targeted audience selection

## Messaging Issues

### Messages Not Delivering

**Symptoms:**

* Template messages not reaching recipients
* No delivery confirmation

**Solutions:**

1. **Check phone number format**
   * Must be E.164 format: +\[country code]\[number]
   * Examples: +14155551234, +442071234567

2. **Verify recipient has WhatsApp**
   * The recipient must have WhatsApp installed
   * Number must be registered with WhatsApp

3. **Check sender status**
   * Sender must be "Online" to send messages
   * Verify in WhatsApp Senders page

4. **Review messaging limits**
   * New senders have limited daily capacity
   * Check your current tier and limits

### Free-form Messages Failing

**Symptoms:**

* Can't send free-form message
* Error about 24-hour window

**Solutions:**

1. **Check the 24-hour window**
   * Free-form messages only work within 24 hours of customer's last message
   * Use a template message instead

2. **Verify conversation exists**
   * The customer must have messaged you first
   * Check conversation history

### AI Not Responding to Messages

**Symptoms:**

* Customer messages arrive but no AI response
* Messages appear in conversation but no reply sent

**Solutions:**

1. **Check assistant connection**
   * Verify an assistant is connected to the sender
   * Ensure "AI Enabled" is turned on

2. **Review assistant status**
   * Assistant must be active and properly configured
   * Test the assistant in the test chat interface

3. **Check for errors**
   * Review conversation for any error messages
   * Check system logs for issues

## Quality & Limits

### Quality Rating Dropped

**Symptoms:**

* Quality rating changed from High to Medium or Low
* Messaging limits reduced

**Causes:**

* High block rates
* Spam reports from recipients
* Low response rates

**Solutions:**

1. **Review recent campaigns**
   * Check which messages triggered blocks or reports
   * Identify problematic content or audiences

2. **Improve targeting**
   * Only message customers who expect to hear from you
   * Remove unengaged contacts from lists

3. **Review message content**
   * Ensure content is valuable and relevant
   * Avoid aggressive or spammy language

4. **Wait for recovery**
   * Quality rating can improve over time with good practices
   * Focus on quality over quantity

### Hitting Message Limits

**Symptoms:**

* Can't send more messages
* Error about daily limit reached

**Solutions:**

1. **Wait for reset**
   * Limits reset daily (24-hour rolling window)
   * Plan campaigns within your current limits

2. **Improve quality**
   * Higher quality ratings unlock higher limits
   * Focus on engagement and avoid blocks

3. **Spread out sends**
   * Don't send all messages at once
   * Implement delays in automation flows

## Connection Issues

### Meta Signup Popup Doesn't Appear

**Symptoms:**

* Clicking "Login with Facebook" does nothing
* Popup blocked or not loading

**Solutions:**

1. **Allow popups**
   * Check browser popup blocker settings
   * Allow popups from the domain

2. **Clear cache**
   * Clear browser cache and cookies
   * Try in incognito/private mode

3. **Try different browser**
   * Some browsers have stricter popup policies
   * Chrome or Firefox typically work best

### Redirected Back Without Completing Setup

**Symptoms:**

* Popup closes but sender not created
* Stuck on step 3

**Solutions:**

1. **Complete all steps**
   * The Meta flow has multiple steps
   * Ensure you completed all of them

2. **Check for errors**
   * Look for error messages in the popup
   * Meta may have rejected the request

3. **Retry the process**
   * Go back to step 2 and select your number again
   * Complete the Meta signup flow carefully

## WhatsApp Calling

### I cannot call a new number

WhatsApp does not allow businesses to ask or call a number that has never written to them. Send a regular template, wait for their reply, then **Ask to call**. Full explanation: [WhatsApp Calling](/whatsapp/calling).

### Ask to call never arrives

The 24-hour chat window is closed, or you already used the 1-ask-per-day limit. Check [session status](/api-reference/whatsapp/session-status) and [call permission](/api-reference/whatsapp/get-call-permission).

### Enable Calling is unavailable

The sender must be online, have an assistant, have a messaging limit of at least 2,000 / 24hr, and must not be Coexistence (WhatsApp Business app).

### Customer allowed but I still cannot call

Consent lasts 7 days. Confirm calling is still enabled, the assistant is assigned, and your balance is not empty. WhatsApp can also revoke consent after several unanswered business calls.

## Getting Help

If you're still experiencing issues:

1. **Check our status page** for any ongoing platform issues
2. **Review Meta's documentation** for WhatsApp-specific policies
3. **Contact support** with:
   * Your sender ID
   * Error messages (exact text)
   * Steps you've already tried
   * Screenshots if applicable


# WhatsApp Automation
Source: https://docs.autocalls.ai/whatsapp/automation

Automate WhatsApp messaging with triggers and actions in the automation platform

The automation platform integrates with WhatsApp to let you send messages automatically, trigger flows from WhatsApp events, and generate AI responses programmatically.

## WhatsApp Calling

Ask for call permission and place WhatsApp calls from automations, or from your own backend via the REST API. The same WhatsApp limits apply.

* Trigger: **WhatsApp voice event** (permission requested / granted / declined, or a WhatsApp call started)
* Actions: **Request WhatsApp call permission**, **Place WhatsApp call**
* REST: [Request call permission](/api-reference/whatsapp/request-call-permission), [Place a WhatsApp call](/api-reference/whatsapp/place-whatsapp-call)
* Custom backends: [Voice events webhook](/api-reference/webhooks/whatsapp-voice-webhook)

Do not start with a Voice Call Request to a brand-new number. Open the chat with a regular template first. Details: [WhatsApp Calling](/whatsapp/calling).

## Available Actions

### Send WhatsApp Template Message

Send a pre-approved template message to a customer.

**Use Cases:**

* Send order confirmations after a purchase
* Trigger appointment reminders on schedule
* Deliver follow-up messages after calls
* Re-engage customers who haven't responded

**Configuration:**

| Field               | Description                                       |
| ------------------- | ------------------------------------------------- |
| **Sender**          | Select your WhatsApp sender (must be online)      |
| **Template**        | Choose from approved templates                    |
| **Recipient Phone** | Customer phone number (E.164 format: +1234567890) |
| **Recipient Name**  | Optional customer name for personalization        |
| **Variables**       | Dynamic values for template placeholders          |

<Tip>
  **E.164 Format** — Phone numbers must be in international format with country code. Examples:

  * ✅ `+14155551234`
  * ✅ `+442071234567`
  * ❌ `(415) 555-1234`
  * ❌ `07123456789`
</Tip>

### Send WhatsApp Message (Free-form)

Send a free-form text message to a customer within the 24-hour messaging window.

<Warning>
  **24-Hour Window Required** — Free-form messages can only be sent to customers who have messaged you within the last 24 hours. For customers outside this window, use a template message.
</Warning>

**Use Cases:**

* Send immediate follow-up to recent conversations
* Deliver time-sensitive information
* Send a file to the customer (menu, brochure, invoice, photo)
* Respond to customer inquiries automatically

**Configuration:**

| Field               | Description                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------- |
| **Sender**          | Select your WhatsApp sender                                                                   |
| **Recipient Phone** | Customer phone number (E.164 format)                                                          |
| **Message**         | Message text (max 4096 characters). Optional when a Media URL is set — it becomes the caption |
| **Media URL**       | Optional public URL of a file to send (image, audio, video, or document)                      |
| **Filename**        | Optional filename shown to the recipient (mainly for documents)                               |

<Tip>
  **Sending files** — Set **Media URL** to a publicly reachable link to the file (a document, image, audio, or video from your storage, CRM, or catalog). WhatsApp fetches it at send time, and earlier steps in your flow can build this URL dynamically (e.g. look up the invoice for an order). The file is delivered to the customer inside the same conversation.
</Tip>

### Request WhatsApp Call Permission

Send **Ask to call** so the customer can allow WhatsApp voice calls.

<Warning>
  The customer must have messaged this sender in the last 24 hours. WhatsApp typically allows one ask per contact every 24 hours and two per week — that counter resets after a connected call.
</Warning>

**Configuration:**

| Field               | Description                          |
| ------------------- | ------------------------------------ |
| **Sender**          | WhatsApp sender with calling enabled |
| **Recipient Phone** | Customer phone number (E.164)        |
| **Recipient Name**  | Optional display name                |

### Place WhatsApp Call

Place an outbound WhatsApp voice call after the customer has granted permission. The sender's assistant joins when they answer.

**Configuration:**

| Field               | Description                                |
| ------------------- | ------------------------------------------ |
| **Sender**          | WhatsApp sender with calling enabled       |
| **Recipient Phone** | Customer phone number (E.164)              |
| **Variables**       | Optional variables passed to the assistant |

<Tip>
  Listen for **Call permission granted** on the WhatsApp voice event trigger, then place the call. Completed calls still fire the regular [post-call webhook](/api-reference/webhooks/post-call-webhook) / Phone call ended trigger.
</Tip>

### Generate AI Reply

Generate an AI response using your assistant, identified by an external customer identifier.

**Use Cases:**

* Build custom chat interfaces
* Integrate WhatsApp with external CRM systems
* Create multi-channel AI responses
* Process messages from external platforms

**Configuration:**

| Field                   | Description                                            |
| ----------------------- | ------------------------------------------------------ |
| **Assistant**           | Select the AI assistant to use                         |
| **Customer Identifier** | Unique customer ID (e.g., phone number, email, CRM ID) |
| **Message**             | The message to respond to                              |
| **Variables**           | Optional context variables for the assistant           |

**How It Works:**

1. The action finds or creates a conversation for the customer identifier
2. Sends the message to your AI assistant
3. Returns the AI-generated response
4. You can then send this response via WhatsApp or other channels

## Triggers

### WhatsApp Message Received

Trigger a flow when a customer sends a WhatsApp message.

**Available Data:**

* Customer phone number
* Message content
* Sender ID
* Timestamp
* Conversation ID

**Example Use Cases:**

* Log messages to a CRM or database
* Send notifications to your team
* Trigger follow-up sequences
* Collect and process customer data

### WhatsApp Conversation Started

Trigger a flow when a new WhatsApp conversation begins.

**Available Data:**

* Customer phone number
* First message content
* Sender information
* Conversation ID

### WhatsApp Voice Event

Trigger a flow when a contact is asked to allow WhatsApp calls, answers that request, or a WhatsApp call starts.

**Available Data:**

* Event type (`call_permission_requested`, `call_permission_granted`, `call_permission_denied`, `voice_call`)
* Customer phone number
* Sender ID
* Conversation ID
* Whether you may place a call (`can_call`)
* Call ID and direction (only on `voice_call`)

**Example Use Cases:**

* Place a WhatsApp call as soon as the customer taps Allow
* Notify your team when a permission request is declined
* Log WhatsApp call starts to a CRM

You can filter the trigger to one event type, or receive every voice event.

<Tip>
  This trigger uses a dedicated webhook on the assistant. It does not replace the New conversation trigger. Custom backends can still listen on the [conversation webhook](/api-reference/webhooks/whatsapp-voice-webhook).
</Tip>

### Conversation Ended

Trigger a flow when a WhatsApp conversation ends (due to inactivity timeout or manual closure).

**Available Data:**

* Full conversation transcript (array of messages and formatted string)
* Extracted variables (from AI post-call evaluation)
* Input variables passed to the assistant
* Customer phone number and name
* WhatsApp sender information (phone number, display name)
* Conversation ID and type
* Message count
* Timestamps (created\_at, ended\_at)

**Example Use Cases:**

* Sync conversation summaries and extracted data to your CRM
* Trigger follow-up sequences based on conversation outcomes
* Log conversation analytics to external systems
* Send satisfaction surveys after conversations end

<Tip>
  The Conversation Ended trigger provides the same payload as the [Conversation Ended Webhook](/api-reference/webhooks/conversation-ended-webhook). Use the webhook for direct integrations, or this trigger for no-code automation flows.
</Tip>

## Example Workflows

### Post-Call WhatsApp Follow-up

Send a WhatsApp template message after a call completes:

```mermaid theme={null}
flowchart LR
    A[Call Completed Trigger] --> B[Wait 5 minutes]
    B --> C{Call Outcome?}
    C -->|Interested| D[Send Interested Template]
    C -->|Follow-up| E[Send Follow-up Template]
    C -->|Not Interested| F[End]
```

**Setup:**

1. Add **Call Completed** trigger
2. Add **Delay** action (optional)
3. Add **Branch** based on call outcome
4. Add **Send WhatsApp Template** action for each branch
5. Configure template and variables

### Lead Qualification via WhatsApp

Qualify leads through WhatsApp conversations:

```mermaid theme={null}
flowchart LR
    A[Form Submission] --> B[Send WhatsApp Template]
    B --> C[Wait for Reply]
    C --> D[AI Processes Response]
    D --> E[Update CRM]
```

### Appointment Reminder Flow

Send automated appointment reminders:

```mermaid theme={null}
flowchart LR
    A[Schedule Trigger] --> B[Fetch Appointments]
    B --> C[Loop Through Appointments]
    C --> D[Send Reminder Template]
    D --> E[Log to Sheet]
```

## Variable Mapping

When sending template messages, map your flow data to template variables:

**Template:**

```
Hi {{1}}, your appointment with {{2}} is confirmed for {{3}}.

Location: {{4}}
```

**Variable Mapping:**

| Template Variable | Flow Data                      |
| ----------------- | ------------------------------ |
| `{{1}}`           | `{{trigger.customer_name}}`    |
| `{{2}}`           | `{{trigger.agent_name}}`       |
| `{{3}}`           | `{{trigger.appointment_date}}` |
| `{{4}}`           | `{{trigger.location}}`         |

## Error Handling

### Common Errors

| Error                      | Cause                                   | Solution                                      |
| -------------------------- | --------------------------------------- | --------------------------------------------- |
| **Template not found**     | Template ID invalid or not approved     | Verify template is approved and ID is correct |
| **Sender offline**         | WhatsApp sender is not online           | Check sender status, ensure it's connected    |
| **Invalid phone number**   | Phone number not in E.164 format        | Format as +\[country code]\[number]           |
| **Outside 24-hour window** | Trying to send free-form outside window | Use a template message instead                |
| **Rate limited**           | Too many messages sent                  | Implement delays between messages             |

### Retry Strategy

For failed messages, implement a retry strategy:

1. Wait 1 minute
2. Retry the action
3. If still failing, log the error and notify your team

## Best Practices

### 1. Always Use Templates for Outbound

When initiating contact with customers, always use approved templates. Free-form messages only work within the 24-hour window.

### 2. Include Opt-Out Options

For marketing messages, include opt-out instructions to comply with regulations and maintain quality rating.

### 3. Respect Rate Limits

Don't send too many messages too quickly. Implement reasonable delays between batch sends.

### 4. Handle Errors Gracefully

Always add error handling to your flows. Log failures and notify your team of issues.

### 5. Test with Single Recipients First

Before running bulk campaigns, test your flow with a single recipient to verify everything works correctly.

### 6. Monitor Quality Rating

Keep an eye on your sender's quality rating. Pause campaigns if you notice declining quality.

## Next Steps

* Learn about [message templates](/whatsapp/templates) and how to create them
* Set up [WhatsApp senders](/whatsapp/senders) for your phone numbers
* Explore the [automation platform](/automation-platform/introduction) for more workflow options


# WhatsApp Calling
Source: https://docs.autocalls.ai/whatsapp/calling

Let customers call your WhatsApp number, and call them back after they grant permission

WhatsApp Calling lets your AI assistant answer voice calls on your WhatsApp Business number, and place outbound WhatsApp calls after the customer agrees.

These rules come from WhatsApp. They apply to every business on the platform — not only this product.

<Info>
  **Start here** — Customers can always call you. You cannot call a brand-new number that has never written to you. They must message you first, then you ask for permission, then they tap Allow.
</Info>

## What you can do

<CardGroup>
  <Card title="Inbound calls" icon="phone-arrow-down-left">
    Anyone can call your WhatsApp Business number. Your connected assistant answers automatically.
  </Card>

  <Card title="Outbound calls" icon="phone-arrow-up-right">
    After a customer allows calling, you can place WhatsApp voice calls to them for 7 days. The same assistant handles the conversation.
  </Card>
</CardGroup>

## How outbound calling works

```mermaid theme={null}
flowchart TD
    A[Customer messages you] --> B[24-hour chat window opens]
    B --> C[You send Ask to call]
    C --> D{Customer taps Allow?}
    D -->|Yes| E[You can call for 7 days]
    D -->|No| F[Wait and ask again later]
    E --> G[Assistant places the WhatsApp call]
```

<Steps>
  <Step title="The customer writes to you">
    They send a WhatsApp message to this sender, or they reply after you send a regular approved template. That opens a **24-hour chat window**.

    A Voice Call Request will **not** be delivered to a number that has never written to you.
  </Step>

  <Step title="You ask for permission">
    In the conversation, click **Ask to call**. WhatsApp shows the customer a permission card. They tap Allow or Decline.
  </Step>

  <Step title="They allow">
    Consent lasts **7 days**. During that window you can place WhatsApp calls from the conversation, the API, or automations.
  </Step>

  <Step title="You call">
    Click **Call**. Your assistant places the WhatsApp voice call. When the call ends, the usual post-call webhook and transcript still apply.
  </Step>
</Steps>

## WhatsApp limits you will hit

These are WhatsApp limits. If a request or call is blocked, it is almost always one of the rows below.

| Limit             | What it means                                                                                                                                                                                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Open 24-hour chat | The customer must have messaged this sender in the last 24 hours before you can ask to call                                                                                                                                                                              |
| 1 ask / 24 hours  | Typically one permission request per contact per day. WhatsApp resets this after a **connected** call (they answered, inbound or outbound)                                                                                                                               |
| 2 asks / week     | Typically two permission requests per contact per week. Same reset after a connected call                                                                                                                                                                                |
| 7-day consent     | After they allow, you can call for 7 days, then you must ask again                                                                                                                                                                                                       |
| Unanswered calls  | WhatsApp can revoke consent after several unanswered business calls                                                                                                                                                                                                      |
| Messaging limit   | The sender needs at least **2,000 messages / 24 hours** before calling can be enabled                                                                                                                                                                                    |
| Number type       | Calling is not available with Coexistence (WhatsApp Business app). Use a Dedicated Platform Number or an External Mobile Number                                                                                                                                          |
| Business country  | You can receive inbound WhatsApp calls on any supported sender. **Ask to call** and outbound WhatsApp calls are not available when the **business number** is in the United States, Canada, Egypt, Vietnam, Nigeria, or Türkiye. The customer's country does not matter. |

<Tip>
  **New contact?** Send a normal utility or marketing template first. Wait until they reply. Then Ask to call. Do not start with the voice-call template — WhatsApp will not deliver it.
</Tip>

## Enable calling on a sender

1. Open **WhatsApp Senders**
2. Confirm the sender is **online**, has an assistant, and shows a messaging limit of at least 2,000 / 24hr
3. Click **Enable Calling**
4. Review the permission-request text (created automatically if you do not already have a Voice Call Request template)

The **WhatsApp Calling** card on that page explains the same flow in the dashboard.

<Warning>
  Coexistence senders (numbers also used in the WhatsApp Business app) cannot use calling. Create a Dedicated Platform Number or connect an External Mobile Number instead.
</Warning>

## Using calling in conversations

Once calling is enabled:

* **Ask to call** appears when the contact has not granted permission yet
* **Call** appears after they allow, until consent expires
* The chat shows activity lines when you asked, when they allowed or declined, and when a call happened

Hover **Ask to call** to see why the button is disabled (for example, you already asked in the last 24 hours).

## API and events

You can ask for permission, check status, and place a call from your own systems:

* [Get call permission](/api-reference/whatsapp/get-call-permission)
* [Request call permission](/api-reference/whatsapp/request-call-permission)
* [Place a WhatsApp call](/api-reference/whatsapp/place-whatsapp-call)
* [WhatsApp voice events](/api-reference/webhooks/whatsapp-voice-webhook)

Completed WhatsApp calls also send the regular [post-call webhook](/api-reference/webhooks/post-call-webhook) if that is enabled on the assistant.

## FAQ

<AccordionGroup>
  <Accordion title="Why can't I call a new phone number directly?">
    WhatsApp does not allow businesses to cold-call or cold-ask numbers that have never written to them. The customer must message you first (or reply to a regular template). That is a WhatsApp rule, not a setting you can turn off here.
  </Accordion>

  <Accordion title="Ask to call did nothing / the customer never saw the request">
    The 24-hour chat window was probably closed. Send a regular approved template, wait for their reply, then ask again. WhatsApp typically allows one ask per contact every 24 hours (two per week) unless a connected call reset that counter. If a previous ask failed to deliver, you may still have to wait.
  </Accordion>

  <Accordion title="The customer allowed, but Call is still missing">
    Confirm calling is still enabled on the sender, the assistant is assigned, and consent has not expired (7 days). Refresh the conversation. If they declined or WhatsApp revoked consent after unanswered calls, you must ask again (subject to the daily/weekly caps).
  </Accordion>

  <Accordion title="Can customers call me without asking first?">
    Yes. Inbound WhatsApp calls do not need a permission request. Anyone who has your WhatsApp number can call it. Your assistant answers.
  </Accordion>

  <Accordion title="Ask to call failed / the customer never saw Allow or Decline">
    If the sender is a US, Canadian, Egyptian, Vietnamese, Nigerian, or Turkish number, WhatsApp does not allow businesses to request outbound calling permission. Inbound calls still work. Use a sender from a supported country to ask and call out.
  </Accordion>

  <Accordion title="Does this work with the WhatsApp Business app on my phone?">
    No. Calling is not supported on Coexistence. Use a Dedicated Platform Number or an External Mobile Number that is not paired with the WhatsApp Business app.
  </Accordion>

  <Accordion title="Why is Enable Calling unavailable?">
    The sender must be online, have an assistant, have a messaging limit of at least 2,000 / 24hr, and not be a Coexistence number. Open **Calling unavailable** on the sender for the exact reason.
  </Accordion>

  <Accordion title="Are WhatsApp calls billed like phone calls?">
    Yes — the assistant still runs a live voice conversation. Minutes (or your plan's voice usage) are consumed. Keep a positive balance before placing calls.
  </Accordion>

  <Accordion title="Can I use this from automations or my backend?">
    Yes. In the automation platform, use the **WhatsApp voice event** trigger plus **Request WhatsApp call permission** and **Place WhatsApp call**. Or call the WhatsApp calling API with your API key. The same WhatsApp limits apply — neither path lets you skip the chat window or consent.
  </Accordion>
</AccordionGroup>

## Troubleshooting

| What you see                        | What to do                                                                                                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ask to call is disabled             | Read the button tooltip. Usually you already asked in the last 24 hours, or they already granted permission.                                                              |
| Request never arrives               | Open chat window first (customer must message you). Then ask. If the sender is a US/CA/EG/VN/NG/TR number, WhatsApp will never deliver Ask to call — inbound still works. |
| Customer says they never got a call | Confirm they tapped Allow, consent is still valid, and your balance is not empty.                                                                                         |
| Enable Calling is hidden            | Sender is Coexistence, offline, missing an assistant, or under the 2,000 / 24hr messaging limit.                                                                          |
| Calls fail right after you enable   | Wait a few minutes and retry. If it still fails, disable calling and enable it again.                                                                                     |

More WhatsApp setup issues: [WhatsApp troubleshooting](/troubleshooting/whatsapp).

## WhatsApp resources

Official WhatsApp / Meta documentation (limits can change on their side):

* [WhatsApp Cloud API Calling](https://developers.facebook.com/docs/whatsapp/cloud-api/calling)
* [User-initiated calls](https://developers.facebook.com/docs/whatsapp/cloud-api/calling/user-initiated-calls)
* [Business-initiated calls](https://developers.facebook.com/docs/whatsapp/cloud-api/calling/business-initiated-calls)
* [Messaging limits](https://developers.facebook.com/docs/whatsapp/messaging-limits)
* [Template messages](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates)

## Next steps

* [Enable calling on a sender](/whatsapp/senders)
* [Voice Call Request templates](/whatsapp/templates)
* [WhatsApp conversations](/whatsapp/conversations)
* [Calling API](/api-reference/whatsapp/request-call-permission)


# WhatsApp Conversations
Source: https://docs.autocalls.ai/whatsapp/conversations

Track and manage AI-powered WhatsApp conversations with customers

WhatsApp conversations are tracked alongside your other conversations, allowing you to review message history, monitor AI performance, and manage customer interactions.

## Viewing WhatsApp Conversations

WhatsApp conversations appear in your **Conversations** section with a "WhatsApp" type badge.

Each conversation includes:

* Complete message history
* Customer phone number
* Connected AI assistant
* Timestamps for all messages
* Cost and usage metrics

## Conversation Types

| Type                        | Description                               |
| --------------------------- | ----------------------------------------- |
| <span>**WhatsApp**</span>   | Customer conversations via WhatsApp       |
| <span>**Web Widget**</span> | Customer conversations via website widget |
| <span>**Test**</span>       | Test conversations from the dashboard     |

## How WhatsApp Conversations Work

### Customer Initiates Contact

1. Customer sends a message to your WhatsApp number
2. System creates or finds existing conversation
3. Message is routed to your AI assistant
4. AI generates and sends response
5. 24-hour messaging window opens

### Within the 24-Hour Window

* AI responds automatically to each message
* Free-form replies are allowed
* Conversation continues naturally

### After 24 Hours

* Customer must message again to reopen window
* You can send template messages to re-engage
* AI remains ready to respond when customer replies

## Conversation Features

### Message History

View the complete back-and-forth between customer and AI:

* Customer messages (incoming)
* AI responses (outgoing)
* Timestamps for each message
* Function calls made during conversation

### Conversation Variables

Variables collected or set during the conversation:

* Customer identifier
* Data extracted by AI
* Context passed from automation flows

### WhatsApp Calling

When calling is enabled on the sender, the conversation header shows **Ask to call** or **Call**. The transcript also records when you asked, when the customer allowed or declined, and when a call happened.

You cannot ask a contact who has not messaged you in the last 24 hours. See [WhatsApp Calling](/whatsapp/calling).

### Cost Tracking

Each conversation tracks:

* Total message count
* Cost per message
* Overall conversation cost

## Managing Conversations

### Filtering Conversations

Filter your conversation list by:

* Type (WhatsApp, Web Widget, Test)
* Assistant
* Date range
* Customer identifier

### Exporting Conversation Data

Export conversation data for analysis:

1. Navigate to Conversations
2. Apply filters as needed
3. Use export options to download data

## AI Assistant Behavior

Your AI assistant handles WhatsApp conversations based on its configuration:

### System Prompt

The same system prompt used for voice calls and web widgets applies to WhatsApp. Ensure your prompt works well for text-based communication.

<Tip>
  **Text-Friendly Prompts** — For assistants that handle both voice and WhatsApp, consider including instructions for text formatting like using bullet points and shorter paragraphs.
</Tip>

### Tools and Functions

AI can call tools during WhatsApp conversations:

* Lookup information in databases
* Schedule appointments
* Transfer to human agents
* Collect and validate data

### Knowledge Bases

Your assistant's knowledge bases are available for WhatsApp conversations, allowing the AI to answer questions using your uploaded content.

## Media in Conversations

### Attachments Gallery

All media files received in WhatsApp conversations (images, audio, video, documents) are stored as attachments. Browse received files in the conversation detail view.

### Image Analysis (Vision)

When a customer sends an image, your AI assistant can analyze it using vision-capable LLMs (OpenAI, Claude, Gemini). The AI's analysis and response are shown in the conversation alongside the original image.

### Voice Note Transcription

Incoming voice messages are automatically transcribed based on your assistant's language settings. The transcribed text appears in the conversation alongside the audio, and the AI responds to the transcribed content.

### Sending Files to Customers

Operators can send files back to customers directly from the conversation UI. This is useful for sharing documents, images, or other resources during a conversation.

## Best Practices

### 1. Review Conversations Regularly

Monitor AI responses to ensure quality. Look for:

* Accurate information
* Appropriate tone
* Successful goal completion
* Customer satisfaction signals

### 2. Train Your AI

Use conversation insights to improve your assistant:

* Identify common questions
* Update knowledge bases
* Refine system prompts
* Add missing tools or functions

### 3. Monitor Response Times

WhatsApp users expect quick responses. Monitor:

* AI response latency
* Any delays or timeouts
* Failed message deliveries

### 4. Handle Escalations

Configure escalation paths for complex issues:

* Transfer to human agent tool
* Collect callback information
* Schedule follow-up calls

## Conversation Metrics

Track key metrics for your WhatsApp conversations:

| Metric                        | Description                                   |
| ----------------------------- | --------------------------------------------- |
| **Total Conversations**       | Number of unique customer conversations       |
| **Messages per Conversation** | Average message count                         |
| **Response Rate**             | Percentage of messages with AI responses      |
| **Average Response Time**     | Time between customer message and AI response |
| **Cost per Conversation**     | Average cost including AI usage               |

## Integration with Other Channels

WhatsApp conversations exist alongside your other communication channels:

* **Phone Calls**: Voice conversations tracked separately
* **Web Widget**: Text conversations from your website
* **API Conversations**: Programmatic chat sessions

All conversation types use the same AI assistant, providing consistent experiences across channels.

## Next Steps

* Learn about [WhatsApp senders](/whatsapp/senders) and sender configuration
* Set up [message templates](/whatsapp/templates) for outbound messaging
* Configure [automation](/whatsapp/automation) for WhatsApp workflows
* Review [AI assistant settings](/ai-assistants/settings/prompt-and-tools) for optimal responses


# WhatsApp Business Integration
Source: https://docs.autocalls.ai/whatsapp/overview

Connect your AI assistants to WhatsApp Business for automated messages and voice calls

<Note>
  **New: External Numbers** — You can now bring your own mobile number to WhatsApp! Use platform numbers or connect your existing mobile number with SMS/voice verification.
</Note>

## What is WhatsApp Business Integration?

WhatsApp Business integration allows you to connect your AI assistants to WhatsApp, enabling automated text-based conversations with customers through the world's most popular messaging platform.

With this integration, you can:

* **Receive customer messages** and respond automatically with AI
* **Send template messages** to start conversations or re-engage customers
* **Use AI-powered replies** for 24/7 customer support
* **Trigger automation flows** based on WhatsApp conversations
* **Answer WhatsApp voice calls** and call customers after they grant permission
* **Track all conversations** in your dashboard

## How It Works

```mermaid theme={null}
flowchart LR
    A[Customer] -->|Sends WhatsApp message| B[Your WhatsApp Sender]
    B -->|Routes to| C[AI Assistant]
    C -->|Generates response| B
    B -->|Replies to| A
```

1. **Create a WhatsApp Sender** using a platform number or your own external number
2. **Connect an AI Assistant** to handle incoming messages automatically
3. **Create Message Templates** for outbound conversations (required by Meta)
4. **Customers message you** and receive AI-powered responses instantly

## Key Components

<CardGroup>
  <Card title="WhatsApp Senders" icon="phone" href="/whatsapp/senders">
    Phone numbers registered for WhatsApp Business messaging
  </Card>

  <Card title="Message Templates" icon="file-lines" href="/whatsapp/templates">
    Pre-approved message formats for business-initiated conversations
  </Card>

  <Card title="AI Conversations" icon="robot" href="/whatsapp/conversations">
    AI-powered automated responses to customer messages
  </Card>

  <Card title="WhatsApp Calling" icon="phone" href="/whatsapp/calling">
    Answer inbound WhatsApp calls and call customers after they grant permission
  </Card>

  <Card title="Automation" icon="bolt" href="/whatsapp/automation">
    Trigger flows and send messages via the automation platform
  </Card>
</CardGroup>

## Understanding WhatsApp Business Rules

WhatsApp has specific rules for business messaging that you need to understand:

### The 24-Hour Messaging Window

<Info>
  When a customer messages you, a **24-hour window** opens where you can send free-form messages. After this window closes, you must use an **approved template** to re-engage the customer.
</Info>

* **Within 24 hours**: Send any message directly
* **After 24 hours**: Must use a pre-approved template message

### Template Messages

Template messages are pre-approved message formats required for:

* Starting new conversations with customers
* Re-engaging customers after the 24-hour window
* Sending notifications, updates, or marketing messages

Templates must be submitted to Meta for approval before use (typically takes minutes to 24 hours).

### Quality Rating & Limits

Meta monitors your messaging quality. New senders start with limited messaging capacity that increases as you maintain good quality:

| Quality Level | Daily Message Limit |
| ------------- | ------------------- |
| New Sender    | \~250 messages      |
| Low Quality   | 1,000 messages      |
| Medium        | 10,000 messages     |
| High Quality  | 100,000+ messages   |

<Warning>
  High block rates or spam reports will lower your quality rating and reduce your messaging limits. Always send relevant, requested content.
</Warning>

## Supported Features

### What's Supported

* **Platform numbers** — Use numbers purchased through our platform with automated AI verification
* **External numbers** — Bring your own mobile number and verify via SMS or voice call
* AI-powered automated replies
* Template messages (Utility, Marketing, Authentication)
* Voice Call Request templates (request permission to call via WhatsApp)
* WhatsApp voice calls (inbound anytime; outbound after the customer allows)
* Conversation history and tracking
* Automation platform integration

### Media & Vision

* **Image analysis (Vision)** — When customers send images, your AI assistant can analyze them using vision-capable LLMs (OpenAI, Claude, Gemini). The AI describes and responds to image content within the conversation.
* **Voice message transcription** — Incoming voice notes are automatically transcribed based on your assistant's language settings. The transcribed text is processed by the AI just like a regular message.
* **Media attachments** — All inbound media (images, audio, video, documents) are stored as attachments on the conversation and accessible from your dashboard.

## Getting Started

<Steps>
  <Step title="Choose Your Number Type">
    Decide whether to use a **platform number** (purchased from us) or your own **external mobile number**. External numbers must be able to receive SMS or voice calls for verification.
  </Step>

  <Step title="Create a WhatsApp Sender">
    Navigate to **WhatsApp Senders** and follow the setup wizard to connect your number to WhatsApp Business.
  </Step>

  <Step title="Connect an AI Assistant">
    Link an AI assistant to automatically respond to incoming messages.
  </Step>

  <Step title="Create Templates">
    Set up message templates for outbound conversations and wait for Meta approval.
  </Step>

  <Step title="Start Messaging">
    Your WhatsApp sender is ready! Customers can message you and receive AI-powered responses.
  </Step>
</Steps>

## Next Steps

* Learn how to [create WhatsApp senders](/whatsapp/senders)
* Turn on [WhatsApp Calling](/whatsapp/calling)
* Understand [message templates](/whatsapp/templates) and approval process
* Set up [automation triggers](/whatsapp/automation) for WhatsApp


# WhatsApp Senders
Source: https://docs.autocalls.ai/whatsapp/senders

Create and manage WhatsApp Business senders for AI-powered messaging

A WhatsApp Sender is a phone number registered with WhatsApp Business API that can send and receive messages. Each sender is connected to an AI assistant for automated responses.

## What is a WhatsApp Sender?

A WhatsApp Sender is:

* A dedicated phone number connected to WhatsApp Business
* Connected to an AI assistant for automated responses
* Capable of sending template messages and free-form replies

## Number Type Options

When creating a WhatsApp sender, you can choose between two types of phone numbers:

<CardGroup>
  <Card title="Platform Numbers" icon="building">
    Use phone numbers purchased through our platform. We handle verification automatically using AI-assisted voice verification.

    **Best for:** Businesses wanting a dedicated business line with automated setup
  </Card>

  <Card title="External Numbers" icon="mobile">
    Use your own mobile number. You verify ownership by receiving an SMS or voice call with a verification code.

    **Best for:** Businesses wanting to use an existing number they already own
  </Card>
</CardGroup>

## Creating a WhatsApp Sender

Creating a WhatsApp sender starts with choosing your number type, then following the appropriate setup flow.

### Step 1: Choose Your Number Type

Navigate to **WhatsApp Senders** → **Create Sender** and select your preferred number type:

* **Platform Number** — Use a number purchased from our platform (automated AI verification)
* **External Number** — Use your own mobile number (SMS/voice code verification)

***

## Platform Number Setup

If you selected **Platform Number**, follow these steps:

### Step 2: Pre-Verify Your Phone Number

Before connecting to WhatsApp, your phone number must be verified with Meta.

<Warning>
  **Call Interception Warning** — During verification, ALL inbound calls to the selected phone number will be intercepted by our verification system for up to 5 minutes.

  This means:

  * Your normal AI assistant will NOT answer calls during this time
  * All calls will go to a silent verification listener
  * Regular customers calling this number will experience disrupted service

  **DO NOT run this on a production phone number that is actively receiving customer calls!**
</Warning>

1. Select an available phone number (only "normal" type numbers not already used for WhatsApp are shown)
2. Enter a **Display Name** for your business (this will be shown to customers)
3. Optionally add business profile information (about, description, address, category)
4. Click **Start Verification**

The system will automatically verify your number with Meta using AI-assisted voice verification. This typically takes 1-2 minutes.

### Step 3: Select Your Verified Number

Once verification completes:

1. You'll see your verified number in the "Verified Numbers Ready" section
2. Select the number you want to connect
3. Click **Continue to WhatsApp Connection**

### Step 4: Connect to WhatsApp Business

This step connects your verified number to WhatsApp through Meta's Embedded Signup flow.

<Warning>
  **CRITICAL: Create a NEW Account** — During the Facebook signup flow, you MUST create a brand new WhatsApp Business Account. Do NOT select an existing WhatsApp Business Account — this will cause the integration to fail.
</Warning>

<Frame>
  <img alt="Click Add New Number in Meta signup" />
</Frame>

**Step A: Click "Add new number"**

When the Meta popup appears, look for the "Add new number" option. Do NOT enter a phone number manually.

<Frame>
  <img alt="Select your pre-verified number" />
</Frame>

**Step B: Select your pre-verified number**

From the dropdown, select the phone number you just verified. It will appear in the list because Meta already knows about it from the verification step.

After selecting your number, complete the remaining steps in Facebook's flow (business verification, permissions, etc.) and you'll be redirected back automatically.

***

## External Number Setup

If you selected **External Number**, follow these steps to connect your own mobile number.

### Requirements Before You Begin

<Info>
  Make sure you have the following ready:

  * **Phone accessible** — You must have your phone nearby to receive a verification code
  * **SMS or calls enabled** — Your number must be able to receive SMS messages or voice calls
  * **Not already on WhatsApp** — This number must not be registered with WhatsApp or WhatsApp Business app
  * **Facebook account** — You'll need a Facebook account to complete the setup
</Info>

### Step 2: Enter Your Phone Number

1. Enter your phone number in international format (e.g., +1 555 123 4567)
2. Enter a **Display Name** for your business
3. Click **Continue**

<Tip>
  **Phone Number Format** — Enter your number starting with + and your country code:

  * US: +1 555 123 4567
  * UK: +44 7911 123456
  * Germany: +49 151 12345678
</Tip>

### Step 3: Connect to WhatsApp Business

Click **Login with Facebook** to open Meta's Embedded Signup flow. Follow these steps:

<Steps>
  <Step title="Login with Facebook">
    A popup will open. Make sure popups are allowed for this site.
  </Step>

  <Step title="Create a WhatsApp Business Account">
    Follow the prompts to create a **new** WhatsApp Business Account. Don't select an existing one.
  </Step>

  <Step title="Enter Your Phone Number">
    When prompted, enter the same phone number you provided in Step 2.
  </Step>

  <Step title="Verify with SMS or Voice Call">
    You'll receive a 6-digit code via SMS or voice call. Enter it to verify your number.
    <Tip>If you don't receive an SMS within 60 seconds, choose the voice call option.</Tip>
  </Step>

  <Step title="Complete the Setup">
    Grant the required permissions and close the popup when finished. You'll be redirected automatically.
  </Step>
</Steps>

### Troubleshooting External Numbers

<AccordionGroup>
  <Accordion title="Popup blocked?">
    Allow popups for this site in your browser settings, then try again.
  </Accordion>

  <Accordion title="Not receiving verification code?">
    Wait 60 seconds, then try the voice call option. Make sure your phone has signal.
  </Accordion>

  <Accordion title="Number already registered?">
    If this number is already on WhatsApp, you'll need to delete that WhatsApp account first before you can use it with WhatsApp Business API.
  </Accordion>

  <Accordion title="Facebook login issues?">
    Make sure you're logged into the correct Facebook account, or try a different browser.
  </Accordion>
</AccordionGroup>

## Sender Status

Your sender can have different statuses during operation:

| Status                      | Description                                             |
| --------------------------- | ------------------------------------------------------- |
| <span>**Online**</span>     | Fully operational. You can send and receive messages.   |
| <span>**Connecting**</span> | Being initialized. Usually takes a few seconds.         |
| <span>**Pending**</span>    | Awaiting verification or approval.                      |
| <span>**Offline**</span>    | Manually disabled. Messages cannot be sent or received. |
| <span>**Suspended**</span>  | Suspended by Meta due to policy violations.             |
| <span>**Failed**</span>     | Setup failed. Check error message for details.          |

## Sender Configuration

### Connect an AI Assistant

Once your sender is online, connect an AI assistant to handle incoming messages automatically:

1. Edit your WhatsApp sender
2. Select an assistant from the dropdown
3. Enable **AI Enabled** toggle
4. Save changes

All incoming messages will now be routed to your AI assistant for responses.

### Keep conversations unread

By default, when your AI assistant replies, the incoming message is marked as read and the customer sees a "typing…" indicator before the reply. If your team also handles chats from the WhatsApp Business app, this makes it hard to tell which conversations still need a person.

Enable **Keep conversations unread** to leave incoming messages marked as unread, so your team can spot the chats that still need attention. A team member marks a conversation as read by opening it in the WhatsApp Business app.

1. Edit your WhatsApp sender
2. Enable the **Keep conversations unread** toggle
3. Save changes

<Note>
  With this enabled, customers no longer see the "typing…" indicator before an AI reply — the typing indicator and the read status are linked, so keeping messages unread also turns the indicator off.
</Note>

### Business Profile

Customize how your business appears to customers:

* **Display Name** — Your business name shown in WhatsApp
* **About** — Short description (max 139 characters)
* **Description** — Detailed description of your business
* **Address** — Business address
* **Business Category** — Industry category (Automotive, Medical, Retail, etc.)
* **Logo** — Business logo image
* **Banner** — Banner image for your profile
* **Websites** — Links to your websites
* **Contact Information** — Additional email and phone contacts

### Read Receipts Webhook

Push delivery and read receipts to your own system whenever a message you send changes status — useful for delivery tracking, read confirmation, and audit trails.

1. Edit your WhatsApp sender and open the **Read Receipts Webhook** section
2. Enter your **Webhook URL** (where status updates will be POSTed)
3. Click **Make test request** to send a sample event and confirm your endpoint receives it
4. Save changes

A **Signing Secret** is generated automatically the first time you save a URL (or run a test). Every request includes an `X-Signature-256` header (HMAC-SHA256 of the body) so you can verify it genuinely came from us — use **Regenerate** to rotate it. Each payload carries the `whatsapp_message_id` returned when you send a message, so you can match every status update to the original.

<Note>
  The `read` status only fires if the recipient has read receipts enabled in their WhatsApp privacy settings. `delivered` always fires.
</Note>

See the [Read Receipts Webhook reference](/api-reference/webhooks/read-receipts-webhook) for the full payload and signature verification.

### WhatsApp Calling

After the sender is online, has an assistant, and a messaging limit of at least 2,000 / 24hr, click **Enable Calling**. Customers can then call this number, and you can call them after they grant permission.

Calling is not available on Coexistence (WhatsApp Business app). Use a Dedicated Platform Number or an External Mobile Number.

Read the full flow, limits, and FAQ: [WhatsApp Calling](/whatsapp/calling).

## Quality Rating & Messaging Limits

Meta tracks your messaging quality and adjusts your limits accordingly.

### Understanding Quality Rating

Your quality rating is based on:

* Block rates (customers blocking your number)
* Spam reports
* Response rates
* Customer feedback

### Messaging Limits

New senders start with limited capacity that increases with good quality:

| Tier   | Daily Limit       | How to Reach                |
| ------ | ----------------- | --------------------------- |
| Tier 1 | \~250 messages    | New sender                  |
| Tier 2 | 1,000 messages    | Maintain quality for 7 days |
| Tier 3 | 10,000 messages   | Consistent high quality     |
| Tier 4 | 100,000+ messages | Enterprise-level quality    |

<Tip>
  **Build Quality First** — Focus on quality conversations before scaling up. Send relevant, requested content to maintain a high quality rating.
</Tip>

## Best Practices

### 1. Choose the Right Number

Select a phone number from a country that matches your target audience. Customers are more likely to engage with local or familiar area codes.

### 2. Set Up Your Display Name Carefully

Your display name appears in customer chats. Use your business name or a clear identifier that customers will recognize and trust.

### 3. Connect an AI Assistant

Link an AI assistant to handle incoming messages automatically. This ensures customers get instant responses 24/7.

### 4. Create Templates Early

Message templates require Meta approval which can take up to 24 hours. Create and submit your templates before you need them.

### 5. Start with Quality Conversations

New senders have messaging limits that increase over time. Focus on quality conversations to build your sender reputation before scaling up.

## Troubleshooting

### Verification Failed

If verification fails, Meta may have temporarily blocked requests. Wait a few minutes before retrying, or try a different phone number.

### Sender Stuck in Pending

If your sender stays in "Pending" status for more than a few minutes:

1. Check if you completed the Meta signup flow
2. Ensure you selected the correct pre-verified number
3. Contact support if the issue persists

### Sender Suspended

If Meta suspends your sender:

1. Review the suspension reason in your sender details
2. Address any policy violations
3. Contact Meta support for appeals

## Next Steps

* Learn about [message templates](/whatsapp/templates) and the approval process
* Set up [automation triggers](/whatsapp/automation) for WhatsApp conversations
* Review [AI assistant configuration](/ai-assistants/what-is-ai-assistant) for optimal responses


# Message Templates
Source: https://docs.autocalls.ai/whatsapp/templates

Create and manage WhatsApp message templates for business-initiated conversations

Message templates are pre-approved message formats required by Meta for business-initiated conversations on WhatsApp. You must have approved templates before you can send outbound messages to customers.

## What are Message Templates?

Message templates are structured messages that:

* Must be submitted to Meta for approval before use
* Allow you to start conversations with customers
* Can include variables for personalization
* Are required for messaging outside the 24-hour window

<Info>
  **Why Templates?** — WhatsApp requires templates to prevent spam and ensure businesses send valuable, relevant messages to customers. All business-initiated messages must use approved templates.
</Info>

## When Do You Need Templates?

| Scenario                      | Template Required?                           |
| ----------------------------- | -------------------------------------------- |
| Customer messages you first   | No — free-form reply allowed within 24 hours |
| Replying within 24 hours      | No — send any message                        |
| Starting a new conversation   | **Yes**                                      |
| Re-engaging after 24 hours    | **Yes**                                      |
| Sending notifications/updates | **Yes**                                      |
| Marketing messages            | **Yes**                                      |

## Template Categories

Templates are organized into categories that determine their approval requirements and use cases:

### Utility Templates

Transactional and service-related messages.

**Use for:**

* Order confirmations
* Shipping updates
* Appointment reminders
* Account notifications
* Payment receipts

**Approval:** Usually approved within minutes

### Marketing Templates

Promotional and sales-related messages.

**Use for:**

* Promotional offers
* Product announcements
* Newsletters
* Sales campaigns
* Re-engagement messages

**Approval:** May take longer, stricter review

<Warning>
  **No Cross-Category Content** — Do not include promotional content in Utility templates. Meta will reject templates with mismatched category and content.
</Warning>

### Authentication Templates

Verification and security messages.

**Use for:**

* One-time passwords (OTP)
* Verification codes
* Login confirmations
* Security alerts

**Approval:** Standard review

### Voice Call Request Templates

Special templates to request permission for WhatsApp voice calls. Enabling calling on a sender can create one for you.

**Use for:**

* Asking a customer for permission to call them on WhatsApp
* Must be sent inside an open 24-hour chat (they messaged you first)

**Approval:** Automatic (when using the standard format)

<Warning>
  WhatsApp will not deliver this template to a brand-new number. Send a regular template first, wait for their reply, then ask to call. Full flow: [WhatsApp Calling](/whatsapp/calling).
</Warning>

## Creating a Template

### Step 1: Navigate to Templates

1. Go to **WhatsApp Senders** → Select your sender → **Templates** tab
2. Or go to **WhatsApp Templates** directly
3. Click **Create Template**

### Step 2: Configure Basic Settings

| Field        | Description                                                                       |
| ------------ | --------------------------------------------------------------------------------- |
| **Name**     | Unique identifier (lowercase, underscores only). Example: `order_confirmation_v1` |
| **Category** | Select Utility, Marketing, Authentication, or Voice Call Request                  |
| **Language** | Template language (must match the content)                                        |

<Tip>
  **Naming Best Practices:**

  * Use descriptive names: `appointment_reminder`, `order_shipped`
  * Include version numbers: `welcome_message_v2`
  * Avoid generic names: ~~`template1`~~, ~~`test`~~
</Tip>

### Step 3: Write Template Content

Templates can include multiple components:

#### Header (Optional)

* **Text Header**: Short headline (up to 60 characters)
* **Media Header**: Image, video, or document (coming soon)

#### Body (Required)

The main message content. This is where you write your message.

**Using Variables:**
Use `{{1}}`, `{{2}}`, etc. for dynamic content:

```
Hi {{1}}, your order {{2}} has been shipped!

Expected delivery: {{3}}
Track your package: {{4}}
```

<Info>
  **Sample Values** — When creating templates, you must provide sample values for each variable. These help Meta understand your template's purpose and are required for approval.
</Info>

#### Footer (Optional)

A short line at the bottom (up to 60 characters). Often used for opt-out info or disclaimers.

#### Buttons (Optional)

Add interactive buttons to your template:

* **Quick Reply**: Pre-defined response buttons (e.g., "Yes", "No", "Learn More")
* **Call to Action**: Link to website or phone number
* **Voice Call Request**: Button to request voice call permission

### Step 4: Submit for Approval

1. Review your template content
2. Click **Submit for Approval**
3. Template status changes to "Pending Approval"
4. Wait for Meta review (minutes to 24 hours)

## Template Approval Process

```mermaid theme={null}
flowchart LR
    A[Create Template] --> B[Submit for Review]
    B --> C{Meta Reviews}
    C -->|Approved| D[Ready to Use]
    C -->|Rejected| E[Edit & Resubmit]
    E --> B
```

### Approval Times

| Category           | Typical Time           |
| ------------------ | ---------------------- |
| Utility            | Minutes to a few hours |
| Marketing          | Hours to 24 hours      |
| Authentication     | Minutes to a few hours |
| Voice Call Request | Usually instant        |

### Template Statuses

| Status                    | Description                         |
| ------------------------- | ----------------------------------- |
| <span>**Draft**</span>    | Not yet submitted                   |
| <span>**Pending**</span>  | Submitted, awaiting Meta review     |
| <span>**Approved**</span> | Ready to use                        |
| <span>**Rejected**</span> | Review failed, see rejection reason |
| <span>**Disabled**</span> | Disabled by Meta due to low quality |

## Common Rejection Reasons

Avoid these common mistakes to improve your approval rate:

### ❌ Promotional Content in Utility Templates

**Problem:** Including discounts, offers, or marketing language in Utility templates.

**Solution:** Use Marketing category for promotional content.

### ❌ Missing or Unclear Variable Samples

**Problem:** Variables like `{{1}}` without clear sample values.

**Solution:** Provide realistic sample values that show the variable's purpose:

* ✅ `{{1}}` = "John Smith"
* ✅ `{{2}}` = "#12345"
* ❌ `{{1}}` = "test"

### ❌ Aggressive or Threatening Language

**Problem:** Content that could be perceived as harassment, threats, or spam.

**Solution:** Use professional, friendly language. Focus on value to the customer.

### ❌ URL Shorteners

**Problem:** Using bit.ly, tinyurl, or other URL shorteners.

**Solution:** Use full, branded URLs from your domain.

### ❌ Incorrect Category Selection

**Problem:** Choosing the wrong category for your content type.

**Solution:** Match category to content purpose strictly.

### ❌ Restricted Content

**Problem:** Templates about alcohol, gambling, adult content, political messaging, or illegal activities.

**Solution:** These are not allowed. Review Meta's commerce policies.

## Using Templates

### Sending Template Messages

Once approved, you can send template messages:

1. **Via Automation Platform**: Use the "Send WhatsApp Template" action
2. **Via API**: Call the send endpoint with template ID and variables

### Variable Replacement

When sending, replace variables with actual values:

**Template:**

```
Hi {{1}}, your appointment is confirmed for {{2}} at {{3}}.
```

**Sent Message:**

```
Hi John, your appointment is confirmed for January 15th at 2:00 PM.
```

## Best Practices

### 1. Use Descriptive Names

```
✅ order_confirmation_v1
✅ appointment_reminder
✅ shipping_update_with_tracking
❌ template1
❌ test
❌ message
```

### 2. Keep Messages Concise

WhatsApp users expect quick, clear messages. Get to the point and include a clear call-to-action.

### 3. Use Interactive Buttons

Add Quick Reply or Call-to-Action buttons to make it easy for customers to respond:

* "Track Order"
* "Contact Support"
* "View Details"
* "Confirm Appointment"

### 4. Test Before Bulk Sending

Always test your template with a single recipient before sending to a large audience. This helps catch formatting issues.

### 5. Create Templates Early

Approval can take up to 24 hours. Create and submit templates before you need them.

### 6. Have Backup Templates

Create multiple versions of important templates. If one is rejected or disabled, you have alternatives ready.

## Editing Templates

<Warning>
  **Limited Editing** — Once a template is approved, you cannot edit it. To make changes, you must create a new template with a different name.
</Warning>

**Can Edit:**

* Draft templates (not yet submitted)
* Rejected templates (fix issues and resubmit)

**Cannot Edit:**

* Approved templates
* Pending templates (must wait for review)

## Template Limits

Meta enforces limits on template creation:

* Maximum templates per WhatsApp Business Account: Varies by account tier
* Template names must be unique per sender
* Rejected templates count toward your limit

## Next Steps

* Set up [automation triggers](/whatsapp/automation) to send templates automatically
* Learn about [WhatsApp senders](/whatsapp/senders) and sender management
* Review [AI assistant configuration](/ai-assistants/what-is-ai-assistant) for conversation responses


# Billing & Payment Management
Source: https://docs.autocalls.ai/white-label/billing

Learn how to manage billing and payments for your white label clients, including rate setting and usage tracking

With White Label, you're in control of how your sub-clients pay:

## 1. Payment Gateway Integration

* **Stripe** is common, but other gateways may be supported.
* Link your gateway in the White Label admin panel, so your brand charges the end-user.

## 2. Setting Rates

* You can define your own per-minute cost, phone number rental price, or monthly subscription tier.
* The difference between what your clients pay and Autocalls.ai's wholesale rates is your profit.

## 3. Usage Tracking

* Each sub-account's minutes, phone numbers, and campaigns are tracked.
* The system automatically calculates monthly usage and potential overages.

## 4. Invoicing

* Typically, you handle invoices to your sub-clients.
* Autocalls.ai bills you for the wholesale usage. You then mark up and bill your clients.

## 5. "Something went wrong" when users upgrade plan

If your users see a **"Something went wrong"** error when trying to upgrade their subscription plan, purchase credits, or rent a phone number, the most common cause is that **Stripe Tax is not configured** on your Stripe Connect account.

### How to fix it

Go to your **Stripe Dashboard** and configure Stripe Tax by following these steps:

1. **Go to [Stripe Dashboard → Settings → Tax](https://dashboard.stripe.com/settings/tax)**

2. **Set your head office address** — this is where your business is located. At minimum, you need to set the country.

3. **Choose a preset product tax code** — select the tax code that best describes what you sell (e.g., "General - Electronically Supplied Services" for SaaS).

4. **Select a default tax behavior** — choose one of:
   * **Exclusive** — tax is added on top of the price
   * **Inclusive** — tax is already included in the price
   * **Inferred by currency** — Stripe decides based on the currency

5. **Add at least one tax registration** — go to the **Registrations** tab and add the jurisdictions where your business is registered to collect tax. Without this, tax will calculate as `0.00`.

<Note>
  All four steps above are **required**. You can verify your setup is complete by checking that your tax settings status shows **"Active"** in the Stripe Dashboard. If it shows "Pending", check which fields are still missing.
</Note>

### Don't need tax collection?

If you don't need automatic tax calculation, contact support to disable it for your account.

### Stripe documentation

* [Set up Stripe Tax](https://docs.stripe.com/tax/set-up)
* [Stripe Tax for platforms](https://docs.stripe.com/tax/tax-for-platforms)
* [Tax Settings API](https://docs.stripe.com/tax/settings-api) — to programmatically check if your account is ready

***

**Note:** Keep an eye on high-usage sub-accounts to avoid unexpected bills. You can set usage caps or alerts to control risk.


# Chat Service Pricing
Source: https://docs.autocalls.ai/white-label/chat-service-pricing

Configure pricing for AI replies, WhatsApp messages, and SMS on your white label platform

Set custom pricing for messaging services on your platform. Charges are deducted from your users' credits or minutes balance when they use these services.

## Accessing Chat Service Pricing

1. Open your Administration Panel
2. Navigate to **Chat Service Pricing** in the sidebar

<Frame>
  <img alt="Chat Service Pricing in sidebar" />
</Frame>

## AI Chat Replies

Configure pricing for AI-generated chat responses. You can choose between two pricing methods:

**Percentage Markup** — apply a markup (0–200%) on top of the platform base cost. The UI shows a real-time breakdown of the platform cost, customer price, and your profit.

<Frame>
  <img alt="AI Chat Replies - Percentage Markup" />
</Frame>

**Fixed Price** — set a fixed price in credits per reply. The minimum is the platform base cost (1.5 credits per reply).

<Frame>
  <img alt="AI Chat Replies - Fixed Price" />
</Frame>

## WhatsApp Messages

Configure pricing for WhatsApp messaging services. Each message type has its own markup slider (0–100%) applied on top of the platform base cost.

<Frame>
  <img alt="WhatsApp Messages pricing configuration" />
</Frame>

* **Inbound Messages** — per message received (base: 0.7 credits)
* **Outbound Messages** — per message sent during a session (base: 0.7 credits)
* **Template Messages** — per template message sent (base: 0.7 credits)

Each section shows the platform base cost, your markup percentage, the final customer price in credits, and your profit.

## SMS Messages

Configure pricing for outbound SMS. Uses a markup slider (0–100%) on top of the platform base cost.

<Frame>
  <img alt="SMS Messages pricing configuration" />
</Frame>

* **Outbound SMS** — per SMS sent (base: 1.0 credits, actual may vary by carrier)

## Credits Exchange

<Frame>
  <img alt="Credits Exchange toggle" />
</Frame>

When enabled, your users can convert their call minutes into chat credits at the platform rate of **9 credits per minute**. This is useful when users have remaining minutes but need credits for messaging services.

## How Credits Work

* **100 credits = \$1 USD**
* **9 credits = 1 minute** (at platform rate)
* Credits are used for: AI replies, WhatsApp messages, and SMS
* Each service deducts the configured amount from the user's credit balance

<Note>
  Changes to pricing take effect immediately for new messages. Existing conversation costs are not affected.
</Note>


# Data Migration
Source: https://docs.autocalls.ai/white-label/data-migration

Migrate assistants, phone numbers, knowledgebases, tools, widgets, and automation flows between users

Transfer data between users on your platform. This tool allows you to copy or move assistants, phone numbers, knowledgebases, custom tools, widgets, and automation flows from one user to another.

## Accessing Data Migration

1. Open your Administration Panel
2. Navigate to **Data Migration** in the sidebar

<Frame>
  <img alt="Data Migration in sidebar" />
</Frame>

## Step 1: Select Users

Choose the **Source User** (migrate FROM) and the **Destination User** (migrate TO). All users in your platform are listed by name and email.

<Frame>
  <img alt="Source and Destination user selection" />
</Frame>

## Step 2: Select Data to Migrate

After selecting a source user, you can pick which items to migrate. All fields are searchable multi-select dropdowns.

### Assistants

Select the assistants you want to migrate. Each assistant is shown with its avatar and name.

<Frame>
  <img alt="Assistant selection" />
</Frame>

When assistants are selected, an **Assistant Migration Options** section appears with these settings:

* **Include attached Knowledgebase** (default: on) — also copy the knowledgebase linked to each selected assistant
* **Include attached Custom Tools** (default: on) — also copy the tools assigned to each selected assistant
* **Transfer Post-Call Webhook Flows** (default: on) — transfer automate flows connected as post-call webhooks
* **Transfer Inbound Webhook Flows** (default: on) — transfer automate flows connected as inbound webhooks
* **Voice Handling:**
  * *Reference existing voice* (recommended) — destination user uses the original voice reference
  * *Copy cloned voice to destination user* — creates a separate copy of the voice

### Phone Numbers, Knowledgebases, Tools, Widgets & Automate Flows

<Frame>
  <img alt="Phone numbers, knowledgebases, tools, widgets and automate flows selection" />
</Frame>

**Phone Numbers** — behavior depends on the type:

* **Normal** (subscribed numbers) — **Grant access**: the source user keeps ownership but only the destination user can use it
* **SIP / Caller ID** — **Full transfer**: ownership moves completely to the destination user

**Knowledgebases, Custom Tools, Widgets** — select standalone items not already attached to the assistants selected above. Items attached to selected assistants are migrated automatically if the corresponding option is enabled.

**Automate Flows** — select automation flows to migrate. Each flow shows its status (enabled/disabled).

<Warning>
  OAuth connections (Google, Slack, etc.) will NOT be transferred. The destination user must reconnect all OAuth apps in their Automate workspace after migration.
</Warning>

## Step 3: Preview & Execute

Once you have selected items, a **Migration Summary** section appears showing the total count of items to be migrated.

<Frame>
  <img alt="Migration summary" />
</Frame>

* **Preview Migration** — performs a dry run to show what would happen, including any warnings
* **Execute Migration** — runs the actual migration after a confirmation prompt

<Frame>
  <img alt="Migration preview result" />
</Frame>

## Migration History

Below the migration form, a **Migration History** table shows all past migrations with:

| Column     | Description                                                                                          |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| **Type**   | Entity type — Assistant, Knowledgebase, Tool, Phone (Grant), Phone (Transfer), Widget, Automate Flow |
| **From**   | Source user name                                                                                     |
| **To**     | Destination user name                                                                                |
| **Status** | Pending, In Progress, Completed, Failed, or Rolled Back                                              |
| **Date**   | When the migration was executed                                                                      |

<Frame>
  <img alt="Migration history table" />
</Frame>

### Rollback

Completed migrations can be rolled back using the **Rollback** button on each row. This deletes the migrated entity from the destination user.

<Warning>
  Rollback cannot be undone. If a migrated assistant is currently attached to campaigns, it cannot be rolled back until removed from those campaigns.
</Warning>


# HIPAA Mode
Source: https://docs.autocalls.ai/white-label/hipaa-mode

Designate individual sub-accounts as HIPAA accounts for healthcare clients

HIPAA mode turns a single sub-account into a healthcare-ready account. Once it is on, that account can only reach the vendors covered by a Business Associate Agreement, and the features that run through vendors without one are switched off.

<Note>
  HIPAA mode has to be unlocked for your platform first. Once it is, a **Enable HIPAA** action appears on every sub-account row in your **Users** table. Contact us if you do not see it and you have healthcare clients to onboard.
</Note>

## What changes on a HIPAA account

Everything below is enforced by the platform, not by policy. Your client cannot switch back to an uncovered vendor by editing an assistant, calling the API, or using the MCP connector.

| Area                      | On a HIPAA account                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| Transcription             | Gladia only                                                                                       |
| Voices                    | ElevenLabs only                                                                                   |
| Language models           | Azure OpenAI only, including the realtime (speech-to-speech) models                               |
| Call recording            | Off by default on every assistant                                                                 |
| Phone numbers             | SIP trunk only — buying a number from the platform and linking a Twilio caller ID are unavailable |
| WhatsApp                  | Unavailable (senders, templates, campaigns and the text fallback)                                 |
| Messenger & Instagram     | Unavailable                                                                                       |
| Automation platform       | Unavailable                                                                                       |
| Two-factor authentication | Required, and cannot be switched off                                                              |

Assistants, calls, campaigns, leads, knowledge bases, mid-call tools, webhooks and the MCP connector all keep working as usual.

## Enabling it for a sub-account

1. Open the **Users** table in your administration panel.
2. Find the sub-account and click **Enable HIPAA**.
3. Read the confirmation dialog — it lists exactly what will change — and confirm.

The row then shows a **HIPAA** badge with the activation date. That date is the record of when the account became a designated HIPAA account, so keep it in mind when your client asks for their paperwork.

### Before you can enable it

The action refuses to continue while either of these is still on the account, and tells you what to remove:

* **Platform phone numbers.** Numbers bought through the platform run on a carrier without a BAA. Release them and connect the client's own carrier with a SIP trunk instead.
* **WhatsApp senders.** Delete them first.
* **Facebook / Instagram connections.** Delete them first.

## Assistants on a HIPAA account

Existing assistants keep working. The first time each one runs after activation, any uncovered provider is replaced with the covered equivalent for that call, so nothing has to be rebuilt by hand.

New assistants are built from the covered set automatically, in both the simple and the advanced editor:

* Where the language has an ElevenLabs voice, the assistant keeps the engine it would normally use, with Gladia for transcription and Azure OpenAI as the model.
* Where the language has no ElevenLabs voice, the assistant is created in speech-to-speech mode on the Azure realtime model, which speaks the language natively.

Call recording is switched off on every existing assistant at activation, and new assistants start with it off. Your client can turn it back on per assistant if they have the consent to record.

## Phone numbers

HIPAA accounts connect telephony through a **SIP trunk**, using the client's own carrier and their own agreement with that carrier. See the SIP trunk guides under Phone Numbers for the provider-specific steps.

## Turning it off

**Disable HIPAA** on the same row returns the account to the standard provider set and gives WhatsApp, Messenger, Instagram, number purchase, caller ID and the automation platform back. Existing assistants keep whatever settings they have at that point — including recording, if it was turned back on.


# White Label Setup
Source: https://docs.autocalls.ai/white-label/onboarding

Step-by-step guide for setting up your white labeled platform

Follow these steps to configure your white label platform:

## 1. Activate White Label

1. Purchase the white label plan
2. Wait for activation confirmation
3. Access your dashboard

## 2. Access Administration Panel

1. Look for the "Administration Panel" button in your dashboard
   <Frame>
     <img alt="Administration Panel Button Location" />
   </Frame>
2. Click to access administration settings

## 3. Configure Platform Settings

Navigate to your Administration Panel settings page to customize your platform. Each configuration section controls different aspects of your branded platform:

### Brand Identity Configuration

<Frame>
  <img alt="Brand Identity Settings" />
</Frame>

**Complete Branding Setup:**

* **Platform Name:** Company name displayed throughout the interface and emails
* **Main Logo:** Primary logo for dashboard header and user interface (light mode)
* **Dark Mode Logo:** Alternative logo for dark theme compatibility
* **Auth Page Image:** Custom image for login/registration pages (light mode)
* **Auth Page Image (Dark):** Alternative auth image for dark theme
* **Favicon:** Browser tab icon (.ico or .png format)
* **Header Background:** Login page background image (light mode)
* **Header Background (Dark):** Login page background for dark theme
* **Logo Height:** Custom logo height in pixels (default: 35px)
* **Page Title:** Authentication page headline text
* **Page Description:** Authentication page subtitle/description
* **SEO Title:** Browser title and search engine optimization
* **SEO Description:** Meta description for search engines
* **SEO Keywords:** Meta keywords for search optimization

**Image Requirements:**

* Logo: PNG/SVG recommended, transparent background
* Auth Images: High resolution JPEG/PNG/WebP (1920x1080 recommended)
* Favicon: 32x32 or 16x16 pixels
* Header Backgrounds: 1920x1080 minimum resolution

### Custom Domain Setup

<Frame>
  <img alt="Custom Domain Configuration" />
</Frame>

**Domain Configuration:**

* **Custom Domain:** Your branded URL (e.g., app.yourcompany.com, platform.yourcompany.com)
* **SSL Certificate:** Automatic HTTPS setup for security (generated automatically)
* **Subdomain Support:** Use any subdomain (app, platform, ai, phone, etc.)

**DNS Setup Requirements:**

* **Record Type:** A record (not CNAME)
* **Host/Name:** Your chosen subdomain (e.g., app, platform)
* **Value/Points to:** Server IP address (provided in settings)

**Critical SSL Requirements:**

* **Add DNS directly without proxy to make SSL work**

**Troubleshooting Domain Issues:**

* SSL certificates generate automatically when DNS is configured correctly
* If SSL fails, check that nameservers aren't adding proxy on top
* Cloudflare users must disable the proxy feature on the DNS record
* Contact support to regenerate SSL if domain setup doesn't work initially
* Allow 24-48 hours for DNS propagation worldwide

### Colors & Theme Customization

<Frame>
  <img alt="Theme Customization Settings" />
</Frame>

**Color Scheme Configuration:**

* **Primary Color:** Main brand color for buttons, links, and accents (default: #01df4a)
* **Gray Color:** Secondary color for borders, backgrounds, and neutral elements
* **Email Header Color:** Color used in email template headers and footers

**Color Application Areas:**

* Button backgrounds and hover states
* Navigation highlights and active states
* Progress bars and loading indicators
* Form focus states and validation
* Email branding consistency

**Best Practices:**

* Choose colors with sufficient contrast (WCAG 2.1 AA compliance)
* Test colors in both light and dark modes
* Maintain consistency across all interface elements
* Consider colorblind accessibility when selecting schemes

### Website URLs Configuration

<Frame>
  <img alt="Website URLs Settings" />
</Frame>

**Essential Platform Links:**

* **Terms of Service URL:** Legal terms and conditions page (displayed in registration)
* **Documentation URL:** Custom documentation site link (replaces default docs)

**URL Requirements:**

* Must use HTTPS protocol (https\://)
* Links should point to your own domain
* Terms of Service link appears in user registration
* Documentation URL replaces default help links throughout platform

**Usage Examples:**

* Terms: `https://yourcompany.com/terms-and-conditions`
* Docs: `https://docs.yourcompany.com` or `https://help.yourcompany.com`

### Footer Links Management

<Frame>
  <img alt="Footer Links Configuration" />
</Frame>

**Custom Footer Links:**

* **Link Text:** Display name (max 50 characters)
* **URL:** Destination link (must be valid URL with https\://)
* **Text Color:** Optional custom color for individual links

**Link Features:**

* Unlimited footer links (recommended: 3-6 links)
* Drag and drop reordering with arrow buttons
* Links only visible to your users (not in tenant admin)

**Common Link Types:**

* Company pages: About Us, Contact, Careers
* Support: Help Center, Documentation, Tutorials
* Legal: Privacy Policy, Terms, Cookie Policy
* Social: LinkedIn, Twitter, Facebook profiles
* Product: Features, Pricing, Case Studies

### Social Login Integration

<Frame>
  <img alt="Social Login Settings" />
</Frame>

**Social Login Control:**

* **Enable Social Logins:** Master toggle for all social authentication
* **Google OAuth Integration:** Google account sign-in for users
* **LinkedIn OAuth Integration:** LinkedIn professional login option

**Google OAuth Configuration:**

* **Google Client ID:** OAuth application identifier from Google Cloud Console
* **Google Client Secret:** Secret key for authentication (hidden/revealable)
* **Redirect URL:** `https://yourdomain.com/login/google/callback`
* **Required Scopes:** Profile information and email access

**LinkedIn OAuth Configuration:**

* **LinkedIn Client ID:** Application ID from LinkedIn Developer Portal
* **LinkedIn Client Secret:** Secret key for LinkedIn authentication
* **Redirect URL:** `https://yourdomain.com/login/linkedin-openid/callback`
* **OpenID Connect:** Uses LinkedIn's OpenID Connect protocol

**Important Notes:**

* Disabling social logins clears all OAuth credentials
* Contact support if social login fails after setup
* Test with actual accounts before going live
* Users can still create regular accounts even with social login enabled

**Setup Documentation:**

* [Google OAuth Setup Guide](/white-label/social-logins/google)
* [LinkedIn OAuth Setup Guide](/white-label/social-logins/linkedin)

### Email Templates Customization

<Frame>
  <img alt="Email Templates Configuration" />
</Frame>

**Welcome Email Configuration:**

* **Email Subject:** Custom subject line for new user welcome emails
* **Email Content (HTML):** Rich text editor for email body content with variables
* **Journey Message:** Text before contact information section
* **Questions Text:** Text before contact email display
* **Contact Email:** Support email address displayed in email footer
* **Email Signature:** Custom signature with tenant name variable

**Available Variables:**

* `{user_name}` - New user's name
* `{tenant_name}` - Your platform name
* `{tenant_domain}` - Your custom domain

**Content Editor Features:**

* Rich text formatting (headings, lists, bold, italic, underline)
* Text alignment and color customization
* Link insertion and blockquotes
* Load default content templates

**Email Branding:**

* Uses email header color from Colors & Theme tab
* Incorporates your platform name and branding
* Professional layout with your contact information
* Responsive design for mobile and desktop

**Testing Templates:**

* Configure SMTP settings first (next section)
* Use the built-in test email feature to preview your template
* Test email shows exactly how your welcome emails will appear to users

### Email SMTP Configuration

<Frame>
  <img alt="SMTP Email Settings" />
</Frame>

**SMTP Server Settings:**

* **SMTP Host:** Mail server hostname (e.g., smtp.gmail.com, smtp.sendgrid.net)
* **SMTP Port:** Server port number (465 for SSL, 587 for TLS, 25 for unsecured)
* **SMTP Username:** Authentication username (usually your email address)
* **SMTP Password:** Authentication password or app-specific password
* **SMTP Encryption:** Security protocol (e.g. TLS)
* **From Address:** Sender email address (e.g., [no-reply@yourdomain.com](mailto:no-reply@yourdomain.com))
* **From Name:** Display name for outgoing emails (e.g., "YourCompany Platform")

**Email Testing:**

* Built-in SMTP test functionality sends test email to your account
* Verifies all SMTP settings before saving
* Test email includes welcome email preview
* 10-second timeout for connection testing

### Custom Scripts Integration

<Frame>
  <img alt="Custom Scripts Configuration" />
</Frame>

**Available Script Fields:**

* **Custom Scripts:** Add your custom scripts here (live chat, feedback, etc). These scripts will be added to all pages.
* **Custom Scripts (Auth):** Add your custom scripts here (live chat, feedback, etc). These scripts will be added to the authentication page.

**Common Use Cases:**

* Live chat widgets (Intercom, Zendesk Chat)
* Analytics tracking (Google Analytics, Facebook Pixel)
* Feedback tools and customer support widgets
* Custom styling or functionality

### Custom Appearance Controls

Control which pages, features, and options are visible to your platform users.

#### Pages & Navigation

Hide entire sections from user navigation:

<Frame>
  <img alt="Custom Appearance - Pages & Navigation" />
</Frame>

* **Automation** — Hide automation/workflow page
* **Assistants** — Hide AI assistants management page
* **Campaigns** — Hide campaigns management page
* **Leads** — Hide leads management page
* **Tools** — Hide tools and integrations page
* **Get Phone Number** — Hide phone number purchase page
* **SMS History** — Hide SMS messaging history page
* **API Keys** — Hide API documentation and keys page
* **Knowledgebase** — Hide knowledgebase management page
* **Conversations** — Hide conversations history page
* **Calls History** — Hide calls history and analytics page
* **Blacklist** — Hide phone number blacklist page
* **Your Phone Numbers** — Hide user's owned phone numbers page
* **Create Custom Dashboard** — Hide custom dashboard creation option
* **WhatsApp Senders** — Hide WhatsApp senders page
* **WhatsApp Templates** — Hide WhatsApp templates page

#### Features & Buttons

Hide specific functionality within pages:

<Frame>
  <img alt="Custom Appearance - Features & Buttons" />
</Frame>

* **Caller ID Button** — Hide caller ID configuration option
* **SIP Integration** — Hide SIP trunking integration button
* **Calendar Integration** — Hide calendar booking features
* **Carrier Costs Display** — Hide call cost information from users
* **Web Widget Feature** — Hide web widget/embed functionality
* **Secondary Languages** — Hide secondary language options for assistants
* **Dashboard Title & Subheading** — Hide dashboard heading text
* **Auto-Generated Plan Features** — Hide auto-generated plan feature descriptions
* **Add Credits Button** — Hide the add credits button and page
* **Plans Page & Button** — Hide the plans page, button and plan badge
* **AI Prompt Editor** — Hide the AI prompt editor
* **Flow Builder** — Hide the flow builder
* **Docs Button** — Hide the documentation button
* **Updates Button** — Hide the updates button and modal
* **Platform Tour** — Hide the platform tour from the dashboard

#### Plan Billing Display

Choose which billing cycles are available on the plans page:

<Frame>
  <img alt="Custom Appearance - Plan Billing Display" />
</Frame>

* **Both Monthly and Yearly** — Show both billing options to users
* **Monthly only** — Only display monthly billing plans
* **Yearly only** — Only display yearly billing plans

#### Phone Number Countries

Restrict which countries are available for phone number purchase:

<Frame>
  <img alt="Custom Appearance - Phone Number Countries" />
</Frame>

* Select countries to hide from the phone number purchase flow
* Search and multi-select for easy configuration
* Hidden countries won't appear as options for your users

### Webhooks Configuration

<Frame>
  <img alt="Webhooks Configuration" />
</Frame>

**Webhook Settings:**
Configure webhooks to receive real-time notifications about platform events on your external systems.

**User Signup Webhook:**

* **Webhook URL:** Endpoint URL that receives POST requests when new users register
* **Format:** Must be a valid HTTPS URL (e.g., `https://yourserver.com/webhook/user-signup`)

**Webhook Payload:**
When a new user signs up on your white-labeled platform, the following JSON payload is sent via HTTP POST:

```json theme={null}
{
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2025-01-15T10:30:00+00:00"
}
```

**Payload Fields:**

| Field        | Type   | Description                               |
| ------------ | ------ | ----------------------------------------- |
| `name`       | string | Full name of the registered user          |
| `email`      | string | Email address of the registered user      |
| `created_at` | string | Registration timestamp in ISO 8601 format |

**Common Use Cases:**

* **CRM Integration:** Automatically add new users to your CRM (HubSpot, Salesforce, etc.)
* **Email Marketing:** Subscribe users to your mailing lists (Mailchimp, ActiveCampaign, etc.)
* **Analytics:** Track signups in your analytics platform
* **Notifications:** Get notified via Slack, Discord, or email when users register
* **Automation:** Trigger onboarding workflows in Zapier, Make, or n8n

**Implementation Tips:**

* Your endpoint should respond with a 2xx status code to acknowledge receipt
* Webhook requests are sent asynchronously and won't block user registration
* Implement proper error handling on your endpoint
* Consider using webhook management services like Zapier Webhooks for easy integration

### Checkout Settings

<Frame>
  <img alt="Checkout Settings" />
</Frame>

* **Require Tax ID / VAT** — when enabled, users must provide their Tax ID or VAT number during Stripe checkout

### Data Retention Policy

<Frame>
  <img alt="Data Retention Settings" />
</Frame>

Set the maximum data retention period your users can configure. Users can choose their own retention period within the limit you set here. If not configured, users can retain data up to 24 months.

**Resource Types:**

| Resource         | Description                               | Range       |
| ---------------- | ----------------------------------------- | ----------- |
| **Calls**        | Call records, transcripts, and recordings | 1-24 months |
| **Leads**        | Lead records within campaigns             | 1-24 months |
| **Chat History** | WhatsApp and web widget conversations     | 1-24 months |
| **SMS**          | SMS message records                       | 1-24 months |

**How It Works:**

* You set the **maximum** retention period per resource type
* Your users can configure their own retention within your limit (in their Profile settings)
* Data older than the configured period is automatically soft-deleted on a recurring schedule
* Default: 24 months for all resource types

<Info>
  If you set a maximum retention of 12 months for calls, your users can choose between 1 and 12 months, but cannot exceed 12.
</Info>

## 4. Set Up Billing

1. Click your user profile
2. Select "Billing platform"
   <Frame>
     <img alt="Billing Dashboard Access" />
   </Frame>
3. Connect your Stripe account to start collecting payments
4. Configure payment settings

## 5. Domain Configuration

1. Choose your domain (e.g., app.yourbrand.com)
2. Add the provided DNS records to your domain
3. Wait for SSL certificate provisioning
4. Test domain access

## 6. Testing

Before launch:

1. Create a test account
2. Verify all branding elements
3. Test the signup process
4. Make test calls
5. Verify billing flow

## Next Steps

* [Configure your pricing plans](/white-label/plans-setup)
* Set up your support channels
* Prepare your marketing materials

***

**Need help?** Contact our support team for assistance with any step of the setup process.


# White Label Platform
Source: https://docs.autocalls.ai/white-label/overview

Learn about our white label solution - your own branded AI calling platform

Our white label solution provides you with your own complete, independently branded version of the Autocalls.ai platform. This is not a subaccount system - it's your own standalone platform with full functionality.

<Frame>
  <img alt="Plans & Pricing Section" />
</Frame>

## Platform Features

You get the exact same powerful platform as Autocalls.ai, but under your brand:

* Complete AI calling capabilities
* Full automation platform
* Independent user management
* Dedicated dashboard
* Custom domain
* Your branding throughout

## Independent Operation

Each of your users gets:

* Independent signup process
* Their own account management
* Direct billing relationship
* Separate credentials
* Individual settings
* Personal dashboard

## Customization Options

Brand the platform as your own:

* Your company name
* Your logo and colors
* Custom domain
* Branded emails
* Your support contact
* Your documentation

## Technical Details

* Separate instance of the platform
* Same features and capabilities as Autocalls.ai
* Regular feature updates
* Independent API access
* Your own analytics

## User Management

Your customers:

* Sign up directly on your platform
* Manage their own accounts
* Handle their own billing
* Access their own dashboard
* Control their settings independently

### Advanced User Controls

* **Individual limit overrides** for specific users
* **Plan customization** beyond standard tiers
* **Usage monitoring** and analytics per user
* **Billing management** with flexible payment terms
* **Resource allocation** based on business needs

## Platform Management Features

### Plan & Limits Management

* **Custom plan creation** with your pricing
* **Resource limits** (assistants, campaigns, calls)
* **Feature toggles** (web widget, automation platform)
* **Usage tracking** and billing automation
* **Upgrade/downgrade** management

### Revenue Management

* **Subscription billing** with Stripe integration
* **Usage-based pricing** with overage calculations
* **Financial analytics** and reporting
* **Tax compliance** and multi-currency support
* **Revenue optimization** tools


# Plans & Pricing Setup
Source: https://docs.autocalls.ai/white-label/plans-setup

Learn how to configure your own pricing plans and limitations for your white labeled platform

Configure custom pricing plans for your platform users through the Administration Panel.

## Accessing Plan Settings

1. Open your Administration Panel
2. Navigate to "Plans" section
   <Frame>
     <img alt="Plans & Pricing Section" />
   </Frame>

## Creating Plans

Create comprehensive pricing plans with detailed configuration options, limits, and pricing structures.

### Plan Configuration Form

<Frame>
  <img alt="Plan Creation Form" />
</Frame>

### General Information Section

**Basic Plan Settings:**

* **Name:** Plan display name shown to customers
* **Description:** Detailed plan description and benefits (required)
* **Order:** Display order in pricing page (numeric value)
* **Is Active:** Enable/disable plan availability
* **Is Featured:** Display featured badge on plan
* **Color:** Plan theme color (Info, Success, Purple, Danger)

**Pricing Configuration:**

* **Included Minutes:** Base minutes included in plan (cannot be changed after creation)
* **Included Chat Credits:** Credits included with the plan for AI replies, WhatsApp messages, and SMS. 9 credits = 1 minute equivalent. (cannot be changed after creation)
* **Extra Minutes Cost:** Price per additional minute (minimum: your platform cost)

### Plan Limits Section

<Frame>
  <img alt="Plan Limits Configuration" />
</Frame>

**Count-Based Limits** (Value -1 for unlimited, 0 to disable):

* **Max Assistants:** Number of AI assistants (default: 1)
* **Max Campaigns:** Outbound calling campaigns (default: 1)
* **Max Cloned Voices:** Voice cloning limit (default: 1, max: 200)
* **Max Knowledgebases:** Knowledge base documents (default: 1)
* **Max Mid Call Tools:** Custom API integrations (default: 1)
* **Max Parallel Calls:** Simultaneous calls (default: 3)
* **Max Automation Runs:** Monthly automation executions (default: 500)
* **Max Own Numbers:** Phone numbers owned (default: 1)

**Feature Toggles:**

* **Web Widget:** Embeddable web calling widget (default: enabled)
* **Secondary Languages:** Multi-language support for assistants (default: enabled)
* **Automation Platform:** Access to workflow automation tools (default: enabled)
* **Calendar Integrations:** Cal.com and GoHighLevel scheduling (default: enabled)
* **Custom Dashboards:** Build personalized analytics dashboards with widgets (default: enabled)
* **AI Prompt Editor:** Access to the AI prompt editor (default: enabled)
* **Flow Builder:** Access to the flow builder (default: enabled)
* **Connect AI:** AI connector for Claude/ChatGPT via MCP (default: enabled)

### Features Display Section

<Frame>
  <img alt="Plan Features List" />
</Frame>

**Plan Features List:**

* Add up to 15 custom features per plan
* Each feature limited to 80 characters
* Features appear as bullet points on pricing page
* Use descriptive benefits and capabilities

**Common Feature Examples:**

* "120 included minutes, then \$0.20 / extra minute"
* "1 assistant"
* "1 outbound campaign"
* "3 calls in parallel"
* "1 cloned voice"
* "24/7 Customer Support"

### Adding Prices to Plans

After creating a plan, scroll down to the **Prices** table:

<Frame>
  <img alt="Plan Creation Interface" />
</Frame>

**Price Configuration Interface:**

* **Billing Type:** Monthly or Yearly (can have both options)
* **Set Your Price:** Customer price with automatic cost validation
* **Cost & Profit Breakdown:** Real-time calculation showing platform costs and your profit

## Default Plan Limits

Navigate to **Default plan limits** in the sidebar to configure global settings:

<Frame>
  <img alt="Default Plan Limits Configuration" />
</Frame>

### Billing Configuration

**Free Account Settings:**

* **Allow Free Accounts:** Enable users to register without payment
* **Free Account Extra Minutes Cost:** Price per additional minute for free users

### Default Limits

<Frame>
  <img alt="Default Plan Limits Configuration" />
</Frame>

Configure baseline limits applied to all new plans:

* **Max Assistants, Campaigns, Cloned Voices**
* **Max Parallel Calls, Knowledge Bases, Own Numbers**
* **Max Mid Call Tools, Automation Runs**
* **Feature toggles:** Web Widget, Secondary Languages, Automation Platform, Calendar Integrations, Custom Dashboards, AI Prompt Editor, Flow Builder, Connect AI

### Plan Structure

* Start with 2-3 clear tiers
* Offer monthly and annual options
* Include reasonable usage limits
* Provide clear upgrade paths

### Pricing Strategy

* Research market rates
* Consider your costs
* Plan for scalability
* Include profit margins

### Feature Distribution

* Clearly differentiate tiers
* Reserve premium features
* Balance value proposition
* Consider upsell opportunities

## Testing Plans

Before launching:

* Create test accounts
* Try different plan combinations
* Test upgrade/downgrade flows
* Verify billing accuracy

<Tip>
  Start with competitive pricing and adjust based on market response and usage patterns.
</Tip>


# Prompt Templates
Source: https://docs.autocalls.ai/white-label/prompt-templates

Create and manage reusable prompt templates for your platform users

Prompt templates allow you to provide pre-built system prompts and initial messages that your users can quickly apply to their AI assistants. This helps maintain consistency and makes it easier for users to get started.

Navigate to **Prompt templates** in the Administration Panel to manage your templates.

## Creating a Template

Click **New prompt template** to create a new template.

### Basic Information

<Frame>
  <img alt="Prompt Template - Basic Information" />
</Frame>

* **Template Type** — choose between:
  * **System Prompt** — the main instructions that define the assistant's behavior
  * **Initial Message** — the first message the assistant sends when a call starts
  * **Flow** — a template specifically for the Flow Builder
* **Call Direction** — whether this template applies to **Inbound** or **Outbound** calls
* **Language Code** — ISO-2 language code (e.g., `en`, `ro`, `fr`)
* **Template Name** — a descriptive name to identify the template

### Template Details

<Frame>
  <img alt="Prompt Template - Details" />
</Frame>

* **Description** — a brief explanation of what the template does, shown to users when selecting templates
* **Display Order** — lower numbers appear first in the list

### Template Content

<Frame>
  <img alt="Prompt Template - Content" />
</Frame>

The actual prompt content written in markdown. This is what gets applied to the assistant when a user selects this template.


# Google App Setup
Source: https://docs.autocalls.ai/white-label/social-logins/google

This document provides instructions on setting up a Google application so users can login/register via Google on your site.

## Enabling API & App Registration

To allow users to log in to your site with their Google account, you need to create a Google Cloud project and configure the OAuth. Follow steps below to create a configure your Google Cloud project.

## 1. Sing in to continue to Google Cloud Platform

Go to [https://console.cloud.google.com/](https://console.cloud.google.com/) and sing in to enter the Google Cloud console.

<Frame>
  <img alt="Google Cloud Console Login" />
</Frame>

## 2. Create a project

Click the project button in the top menu and you'll see the **Select a project** pop-up. Click the **NEW PROJECT** button create a project.

<Frame>
  <img alt="Google Create Project" />
</Frame>

Enter the **Project name** and click the **CREATE** button.

<Frame>
  <img alt="Google Project Name" />
</Frame>

## 3. Start to configure the OAuth consent screen

Once a project is created, go to **APIs & Services**. Select **Credentials** from the left-side menu then click the **CONFIGURE CONSENT SCREEN** button.

<Frame>
  <img alt="Google Credentials" />
</Frame>

<Frame>
  <img alt="Google Credentials" />
</Frame>

Choose the External in the User Type options, then click the CREATE button.

<Frame>
  <img alt="Google Create Button" />
</Frame>

## 4. Edit app registration

### 4.1 OAuth consent screen

Enter the **App name**, **User support email**, upload **App logo**.

Enter the **Application home page**, **Application privacy policy link**, **Application terms and service link**.

Enter your website **domain**.

Enter your contact **Email addresses**.

Continue to the next step by clicking the **SAVE AND CONTINUE** button.

<Frame>
  <img alt="Google Edit Registration" />
</Frame>

### 4.2. Scopes

You'll be on the step **Scopes**. Click the **ADD OR REMOVE SCOPES** button to select the scopes.

<Frame>
  <img alt="Google Scopes" />
</Frame>

Select three required API Scopes:

* **.../auth/userinfo.email**
* **.../auth/userinfo.profile**
* **openid**

Once selected click on the **UPDATE** button.

<Frame>
  <img alt="Google Required API Scopes" />
</Frame>

The selected scopes will now appear on the **Your non-sensitive scopes** section.

Continue to the next step by clicking on the **SAVE AND CONTINUE** button.

<Frame>
  <img alt="Google Sensitive Scopes" />
</Frame>

### 4.3 Test users

You'll be on the step **Test users**. On this step you can add Test users to test the social login, or just continue to the next step by clicking the **SAVE AND CONTINUE** button.

<Frame>
  <img alt="Google Test Users" />
</Frame>

### 4.4 Summary

You'll be on the step **Summary** that shows you the outline of your app registration. Click the **BACK TO DASHBOARD** button.

<Frame>
  <img alt="Google Summary" />
</Frame>

## 5. Create credentials

Select **Credentials** from the left-side menu. Click the **CREATE CREDENTIALS** button and select the **OAuth client ID** item.

<Frame>
  <img alt="Google Create Credentials" />
</Frame>

Once clicked, it'll take you to the **Create OAuth client ID** page.

Select the **Web application** option in the **Application type**. Enter a name of your OAuth 2.0 client in the Name field.

Enter allowed redirect URLs in the **Authorized redirect URIs** section.

See example:

* **[https://sss.com/login/google/callback](https://sss.com/login/google/callback)**

<Note>By default, URLs have the "/" symbol at the end of the path. Remove "/" before "?" if your site uses URLs without "/" at the end of the path.</Note>

Click the **CREATE** button.

<Frame>
  <img alt="Google Create OAuth Client" />
</Frame>

## 6. Enter your keys

Once you click the button, the **OAuth client created** pop-up will appear and you'll see your application keys.

<Frame>
  <img alt="Google OAuth Client Created" />
</Frame>

Copy your **Client ID** and **Client Secret** keys and paste them to the **Client ID** and **Client secret** fields under the **Google Login Configuration** on the white-label > Settings > Social Logins.

<Frame>
  <img alt="White Label Google Configuration" />
</Frame>

## Test

Test the Social Login feature at the Login and Registration pages. If you're encountering issues, please contact our support team for assistance with any step of the setup process.

<Frame>
  <img alt="Google login test" />
</Frame>

***

**Need help?** Contact our support team for assistance with any step of the setup process.


# LinkedIn App Setup
Source: https://docs.autocalls.ai/white-label/social-logins/linkedin

This document provides instructions on correctly setting up a LinkedIn application so that users can log in/register via LinkedIn on your site.

## Creating a new app

You need to create a LinkedIn app to allow users to log in to your site with their LinkedIn accounts. To create a new LinkedIn app, please do the following:

* Go to the LinkedIn developer site: [https://developer.linkedin.com/](https://developer.linkedin.com/).
* Click the “Create App” button on the banner.
* To correctly create the application, please fill in the application sections, which are explained below.

## Create an app

* **Application Name**  – Enter a name for your application.
* **Company name**  – Select an existing company or choose a New Company. If you select the new company, you will be asked to enter a company name.
* **Description**  – Enter a name for your application.
* **Business Email**  – Enter your email address.
* **Legal terms**  – Read the terms of service and check the box to confirm that you have read and agree to the terms.

Click the project button in the top menu and you'll see the **Select a project** pop-up. Click the **NEW PROJECT** button create a project.

<Frame>
  <img alt="LinkedIn Create App" />
</Frame>

## Products

Once you have clicked on the **Create app** button, you'll be redirected to the Products tab.

<Frame>
  <img alt="Linkedin Products Tab" />
</Frame>

Scroll down the product list until you find **Sign In with LinkedIn using OpenID Connect** and click the **Request Access** button.

<Frame>
  <img alt="LinkedIn OpenID Connect" />
</Frame>

Read the terms; if you agree with the terms, click on the checkbox and proceed by clicking on the **Request Access** button.

<Frame>
  <img alt="LinkedIn Request Access" />
</Frame>

## Auth

Go to the Auth tab and add Redirect URLs.

<Frame>
  <img alt="LinkedIn Auth Tab" />
</Frame>

## OAuth 2.0 settings

In the redirects URLs, you just need to enter your site e.g.: [https://sss.com/login/linkedin-openid/callback](https://sss.com/login/linkedin-openid/callback)

<Frame>
  <img alt="LinkedIn Redirect URI" />
</Frame>

## Scopes

The OAuth 2.0 scopes will appear a few seconds after you have added and updated the redirect URLs in OAuth 2.0 Settings.

<Frame>
  <img alt="LinkedIn OAuth Scopes" />
</Frame>

## Application details

If the app is successfully created, you will see the following details.

<Frame>
  <img alt="LinkedIn App Details" />
</Frame>

You will need to copy the **API Key** and **Secret Key** and add them to the white-label > Settings > Social Logins > LinkedIn Login Configuration.

<Frame>
  <img alt="LinkedIn App Details" />
</Frame>

***

**Need help?** Contact our support team for assistance with any step of the setup process.


# User Limits Management
Source: https://docs.autocalls.ai/white-label/user-limits

Configure individual user limits and restrictions for your white label platform users

Manage individual user limits and restrictions beyond the default plan limits. This allows you to customize specific users' access without changing their plan.

## Overview

User limits provide granular control over individual users on your white label platform. You can override plan limits for specific users, giving them more or less access than their plan normally allows.

## Accessing User Settings

<Frame>
  <img alt="Users Table Interface" />
</Frame>

1. Go to the **Users** table in your administration panel
2. Click the **Edit** button on any user row to open their profile

## User Information & Access

<Frame>
  <img alt="User Information Settings" />
</Frame>

Manage basic user details and administration panel access permissions.

**Basic Information:**

* **Name** — User's display name
* **Email** — User's email address (used for login and notifications)

**Administration Panel Access:**

<Warning>
  These permissions grant access to the **Administration Panel** — the tenant management area where you configure your white label platform. Only enable these for team members who need to manage the platform itself, not for regular end users.
</Warning>

* **Platform Admin** — Full administrative access to the administration panel. Can manage users, configure all settings, and access all resources. Use for trusted administrators who need complete control.
* **Settings Access** — Can access and modify the administration panel settings page (branding, appearance, email templates, etc.) but cannot manage other users. Use for team members who need to configure the platform without user management.
* **Billing Access** — Can access the billing dashboard, manage payment methods, view invoices, and update billing information. Use for finance team members or accounting staff.

<Note>
  These permissions only apply to tenant users. The tenant owner always has full access by default.
</Note>

## Custom User Limits

Enable **"Custom Limits"** to override plan defaults for this specific user.

<Frame>
  <img alt="Custom User Limits" />
</Frame>

### Count Limits

Numerical restrictions on resource usage. Set **-1** for unlimited, **0** for disabled, or a positive number for a specific limit.

| Limit                   | Description                                         |
| ----------------------- | --------------------------------------------------- |
| **Max Assistants**      | Maximum number of AI assistants the user can create |
| **Max Campaigns**       | Maximum number of outbound campaigns                |
| **Max Cloned Voices**   | Maximum number of custom voice clones               |
| **Max Knowledgebases**  | Maximum number of knowledge bases                   |
| **Max Mid Call Tools**  | Maximum custom mid-call tools                       |
| **Max Parallel Calls**  | Maximum simultaneous calls                          |
| **Max Automation Runs** | Monthly automation platform executions              |
| **Max Own Numbers**     | Maximum phone numbers user can add (SIP/Caller ID)  |

### Boolean Limits

| Feature                 | Description                                         |
| ----------------------- | --------------------------------------------------- |
| **Web Widget**          | Access to embeddable web widget functionality       |
| **Secondary Languages** | Access to multi-language assistant support          |
| **Automation Platform** | Access to no-code automation workflows              |
| **Custom Dashboards**   | Access to create and manage custom dashboards       |
| **AI Prompt Editor**    | Access to the AI prompt editor                      |
| **Flow Builder**        | Access to the flow builder                          |
| **Connect AI**          | Access to the AI connector (Claude/ChatGPT via MCP) |

## Custom User Appearance

<Frame>
  <img alt="Custom User Appearance" />
</Frame>

Customize what individual users can see and access on your platform, independent of your global appearance settings. Enable **"Custom Appearance"** to override global settings for this user.

Checkboxes start with your current global settings as defaults. Check a box to **hide** that page or feature from the user.

### Hide Pages

<Frame>
  <img alt="Custom User Appearance - Hide Pages" />
</Frame>

* Automation, Assistants, Campaigns, Leads, Tools
* Get Phone Number, SMS History, API Keys
* Knowledgebase, Conversations, Calls History
* Blacklist, Your Phone Numbers, Create Custom Dashboard
* WhatsApp Senders, WhatsApp Templates

### Hide Features

<Frame>
  <img alt="Custom User Appearance - Hide Features" />
</Frame>

* Caller ID Button, SIP Integration
* Calendar Integration, Carrier Costs Display
* Web Widget, Secondary Languages, Dashboard Title & Subheading
* Add Credits Button, Plans Page & Button
* AI Prompt Editor, Flow Builder
* Docs Button, Updates Button & Modal

### Visible Plans

<Frame>
  <img alt="Custom User Appearance - Visible Plans" />
</Frame>

Restrict which plans the user can see. Select specific plans from the dropdown — leave empty to show all active plans. You can also assign inactive or hidden plans to specific users.

<Note>
  User appearance settings override global settings. If no custom setting exists for a feature, the global configuration applies.
</Note>

<Warning>
  Custom limits and appearance settings do not apply to the tenant owner.
</Warning>

## Manage Balance

Click the **Balance** button on any user row to open the balance management modal. This shows the current balances and lets you transfer minutes or credits.

<Frame>
  <img alt="Balance Overview" />
</Frame>

The modal shows both the **user's balance** (minutes and credits) and **your balance** as the platform owner side by side.

### Transfer Call Minutes

Transfer call minutes between your balance and a user's balance.

<Frame>
  <img alt="Transfer Call Minutes" />
</Frame>

* Choose **Add to user** or **Remove from user**
* Enter the amount in minutes
* The maximum you can transfer is limited by the source balance

### Transfer Chat Credits

Transfer chat credits used for AI replies, WhatsApp messages, and SMS. Credits are deducted from your minutes balance at a rate of **9 credits = 1 minute**.

<Frame>
  <img alt="Transfer Chat Credits" />
</Frame>

* Choose **Add to user** or **Remove from user**
* Enter the amount in credits
* When adding credits, the equivalent minutes are deducted from your balance
* When removing credits, the equivalent minutes are returned to your balance

## Troubleshooting

**User can't create resources:**

* Check current vs. limit usage
* Verify limit type (count vs. boolean)
* Confirm user is on correct plan

**Limits not applying:**

* Clear platform cache
* Verify limit configuration
* Check for conflicting settings

<Warning>
  Unlimited settings (-1) should be used carefully as they can impact platform performance and costs.
</Warning>

<Note>
  User limits override plan limits. A user's effective limit is always the user limit if set, otherwise the plan limit applies.
</Note>