> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstwork.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Caller

> Deploy AI-powered voice bots to screen candidates, collect information, and automate phone interactions

## Overview

The **AI Caller** enables you to deploy intelligent voice bots that can call candidates, conduct phone screenings, collect responses, and feed data back into your hiring flows. It integrates with major telephony providers to deliver natural, conversational AI experiences at scale.

## How It Works

```mermaid theme={null}
graph LR
    A[Configure Bot] --> B[Enroll Candidates]
    B --> C[AI Makes Call]
    C --> D[Conversation Recorded]
    D --> E[Responses Mapped to Forms]
    E --> F[Automations Triggered]
```

1. **Configure a Caller Bot** — Define the conversation script, questions, and behavior
2. **Enroll candidates** — Assign candidates to be called (manually or via automation)
3. **AI conducts call** — The bot calls the candidate and follows the script
4. **Responses captured** — Candidate responses are transcribed and stored
5. **Data mapped** — Responses are mapped to form fields in the hiring flow
6. **Automations fire** — Follow-up actions trigger based on responses

## Setting Up an AI Caller Bot

### Create a new Caller Bot

Navigate to **Settings → AI Caller** and click **New Caller Bot**. Give it a descriptive name that reflects its purpose (e.g., "Warehouse Pre-Screen" or "Onboarding Welcome Call").

### Select a telephony provider

Choose the telephony provider for outbound calls. The provider determines which phone numbers and regions are available. See [Telephony Providers](#telephony-providers) below.

### Configure voice and language

Pick an AI voice and conversation language. You can preview voices before selecting. The bot will conduct the entire call in the selected language.

### Design the conversation script

Build the conversation flow using the script editor. Define an introduction, questions, follow-up prompts, and a closing message. See [Designing Conversation Scripts](#designing-conversation-scripts) for guidance.

### Map responses to form fields

Connect each question in the script to a form element in your hiring flow. This ensures candidate answers are automatically saved as structured data.

### Set scheduling and retry policies

Configure when calls should be placed and how the bot handles unanswered calls. See [Scheduling & Retries](#scheduling--retries).

### Attach a knowledge base (optional)

Link one or more knowledge bases so the bot can answer candidate questions during the call.

### Activate the bot

Enable the bot. Candidates can now be enrolled manually or through automations.

## Caller Bot Configuration

| Setting              | Description                                                                            |
| -------------------- | -------------------------------------------------------------------------------------- |
| Name                 | Bot identifier visible to your team                                                    |
| Script               | Conversation flow, questions, and branching logic                                      |
| Voice                | AI voice selection (multiple voices per language)                                      |
| Language             | Conversation language                                                                  |
| Telephony Provider   | Twilio, Plivo, or Exotel                                                               |
| Caller ID            | The outbound phone number candidates see                                               |
| Form Mapping         | How responses map to form fields                                                       |
| Retry Policy         | How many times to retry unanswered calls                                               |
| Schedule             | When calls should be placed                                                            |
| Max Call Duration    | Maximum length before the bot wraps up                                                 |
| Short Drop Duration  | Minimum call length to count as a real call (default: 10s)                             |
| Realtime Model       | GPT Realtime model powering the conversation (Standard, Mini, or 1.5)                  |
| Smooth Barge-in      | Makes the caller smoothly interrupt the bot mid-sentence for natural conversation flow |
| Conversation History | Include summaries from prior calls for context continuity                              |
| Knowledge Base       | Reference material the bot can use to answer questions                                 |

> \[!NOTE]
> **Tool Calling** and **Knowledge Base** are configured in their own dedicated tabs within the bot editor. See [Tool Calling](#tool-calling-mid-call-automations) and [Knowledge Bases](#knowledge-bases) for details.

## Designing Conversation Scripts

The script defines what the bot says and asks during a call. A well-designed script feels natural while reliably collecting the data you need.

### Script Structure

Every script has four sections:

| Section          | Purpose                                  | Example                                                                      |
| ---------------- | ---------------------------------------- | ---------------------------------------------------------------------------- |
| **Introduction** | Greet the candidate and explain the call | "Hi, this is an automated call from Acme Corp regarding your application..." |
| **Questions**    | Collect specific information             | "What is your availability to start?"                                        |
| **Follow-ups**   | Clarify or dig deeper based on answers   | "You mentioned weekends — does that include both Saturday and Sunday?"       |
| **Closing**      | Summarize and end the call               | "Thank you for your time. We'll be in touch within 48 hours."                |

### Branching Logic

Scripts support conditional branching so the conversation adapts based on candidate responses:

```mermaid theme={null}
graph TD
    Q1["Do you have a valid driver's license?"] -->|Yes| Q2["What class of license?"]
    Q1 -->|No| Q3["Are you willing to obtain one?"]
    Q3 -->|Yes| Q4["Great, we can discuss timeline"]
    Q3 -->|No| END["Thank you, we'll review your application"]
    Q2 --> Q5["Next question..."]
```

### Script Tips

Avoid open-ended questions when you need structured data. Instead of "Tell me about yourself," ask "How many years of warehouse experience do you have?"
For critical information like start dates or certifications, have the bot repeat the answer back: "Just to confirm, you said you can start on March 15th — is that correct?"
The AI can handle off-script responses, but providing explicit fallback prompts improves the experience. For example: "I didn't quite catch that. Could you repeat your answer?"
Aim for 3–5 minutes per call. Candidates are more likely to complete shorter calls, and shorter calls have higher data quality.

## Caller Enrollments

A **Caller Enrollment** represents a candidate assigned to receive an AI call.

### Enrollment Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Initiated : Candidate enrolled
    Initiated --> UserUnreachable : User Busy / Unanswered
    Initiated --> InProgress : Call placed
    InProgress --> Completed : Call finished successfully
    InProgress --> ShortDrop : Call ended too quickly
    InProgress --> IdentityMismatch : Wrong person answered
    InProgress --> RescheduleRequired : Candidate asked to reschedule
    InProgress --> UserUnreachable : No answer / busy / voicemail
    InProgress --> ConnectionError : Telephony failure
    InProgress --> TimedOut : Max duration exceeded
    InProgress --> Failed : Call error
    Completed --> [*]
    Failed --> [*]
```

### Enrollment Fields

| Field          | Description                                                                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Candidate      | The candidate to be called                                                                                                                                   |
| Caller Bot     | Which bot configuration to use                                                                                                                               |
| Status         | Current state (Initiated, In Progress, Completed, Failed, Short Drop, Identity Mismatch, Reschedule Required, Connection Error, User Unreachable, Timed Out) |
| Attempts       | Number of call attempts made                                                                                                                                 |
| Scheduled Time | When the next call attempt is planned                                                                                                                        |
| Call Duration  | Length of the completed call                                                                                                                                 |
| Transcript     | Full conversation transcript                                                                                                                                 |
| Extracted Data | Structured data extracted from responses                                                                                                                     |

### Creating Enrollments

Enrollments can be created in three ways:

1. **Manually** — Select candidates from the application list and enroll them in a caller bot
2. **Via automation** — Trigger enrollment when a candidate enters a stage, submits a form, or meets specific criteria
3. **In bulk** — Enroll multiple candidates at once using [Bulk Operations](/features/bulk-operations)

## Form Mapping

**Caller Form Mappings** define how AI-extracted responses populate form fields in the hiring flow.

### Mapping Types

| Mapping Type           | Description                                | Example                                                   |
| ---------------------- | ------------------------------------------ | --------------------------------------------------------- |
| **Direct Value**       | Maps the response directly to a field      | "What city do you live in?" → City text field             |
| **Boolean**            | Converts yes/no answers to checkbox values | "Do you have a driver's license?" → License checkbox      |
| **Date Extraction**    | Parses dates from natural language         | "When can you start?" → Start date field                  |
| **Numeric Extraction** | Pulls numbers from responses               | "How many years of experience?" → Experience number field |
| **Selection Match**    | Matches response to dropdown/radio options | "Day shift or night shift?" → Shift preference dropdown   |
| **Email**              | Extracts an email address                  | "What's your email?" → Email field                        |
| **Phone Number**       | Extracts a phone number                    | "What's your contact number?" → Phone field               |
| **Full Transcript**    | Stores the complete answer as text         | "Tell me about your experience" → Experience text area    |

### Mapping Configuration

| Setting       | Description                                    |
| ------------- | ---------------------------------------------- |
| Bot Question  | The question in the script to map from         |
| Form Element  | The target form field                          |
| Mapping Type  | How to transform the response                  |
| Default Value | Value to use if the question wasn't answered   |
| Validation    | Optional rules to validate the extracted value |

> \[!NOTE]
> Form mappings run after the call completes. If a mapped value fails validation, the enrollment is flagged for manual review rather than writing invalid data.

## Telephony Providers

The AI Caller supports three telephony providers. The platform can automatically select the best provider based on the candidate's phone number and region.

| Provider   | Regions    | Features                                              |
| ---------- | ---------- | ----------------------------------------------------- |
| **Twilio** | Global     | SMS + Voice, robust API, widest coverage              |
| **Plivo**  | Global     | Cost-effective, good international coverage           |
| **Exotel** | India, SEA | Regional coverage, local numbers, competitive pricing |

### Provider Configuration

Each provider requires:

* API credentials (API key / auth token)
* At least one provisioned phone number for outbound calls
* Webhook URL configuration for call status updates

See the [Twilio Integration](/integrations/twilio) guide for detailed setup instructions.

## Scheduling & Retries

### Call Windows

Configure when the AI Caller is allowed to place calls:

| Setting            | Description                                    | Example            |
| ------------------ | ---------------------------------------------- | ------------------ |
| **Time Zone**      | The candidate's local time zone                | `America/New_York` |
| **Allowed Hours**  | Hours during which calls can be placed         | 9:00 AM – 7:00 PM  |
| **Allowed Days**   | Days of the week calls are permitted           | Monday – Saturday  |
| **Blackout Dates** | Specific dates when calls should not be placed | Public holidays    |

> \[!NOTE]
> Call windows are evaluated in the **candidate's local time zone** based on their phone number's country code. This prevents calls at inappropriate hours for international candidates.

### Retry Policy

| Setting          | Description                       | Default  |
| ---------------- | --------------------------------- | -------- |
| Max Attempts     | Maximum number of call attempts   | 3        |
| Retry Interval   | Time between retry attempts       | 4 hours  |
| Backoff Strategy | How retry intervals increase      | Linear   |
| Abandon After    | Stop retrying after this duration | 72 hours |

When a call goes unanswered:

1. The enrollment status moves to **No Answer**
2. A retry is scheduled based on the retry interval and backoff strategy
3. If max attempts are reached, the enrollment moves to **Failed**
4. A failed enrollment can trigger automations (e.g., send an SMS asking the candidate to call back)

## Tool Calling (Mid-Call Automations)

AI Caller bots can invoke automations during a live call — enabling real-time actions like scheduling interviews, sending emails, or updating records while the conversation is still in progress.

### How It Works

1. **Link automations to the bot** — Connect one or more automations and define when each should be triggered
2. **Provide a tool description** — Describe when the AI should invoke the automation (e.g., "Use this when the candidate confirms they want to schedule an interview")
3. **Define a payload schema** — Specify the data fields the AI needs to collect before invoking the automation
4. **AI decides and acts** — During the call, the AI determines when to invoke a tool, collects the required data, and triggers the automation in the background

> \[!NOTE]
> Tool calls run asynchronously. The call continues naturally while the automation executes in the background.

## Smooth Barge-in

With **Smooth Barge-in** enabled, the bot uses local Silero-based voice activity detection to detect when a candidate speaks over the bot. The bot stops talking and yields the floor only if required, creating a more natural conversation flow. Disabled by default.

## Knowledge Bases

Caller bots can reference **Knowledge Bases** — collections of information the AI uses to answer candidate questions during calls.

### What to Include

* Company policies and FAQs
* Job descriptions and requirements
* Benefits and compensation details
* Location and schedule information
* Parking, dress code, and first-day instructions

### Managing Knowledge Bases

Knowledge bases are managed at the company level and can be shared across multiple caller bots.

### Create a knowledge base

Navigate to **Settings → AI Caller → Knowledge Bases** and click **New Knowledge Base**.

### Add content

Upload documents or paste text content. Supported formats include PDF, DOCX, and plain text. Content is automatically indexed for retrieval.

### Attach to a caller bot

In the caller bot configuration, select one or more knowledge bases. The bot will reference them when candidates ask questions outside the script.

> \[!NOTE]
> The AI only references knowledge base content when a candidate asks a question. It does not proactively recite information unless it's part of the script.

## Conversation History

Every completed call is automatically summarised. When **Conversation History** is enabled, the bot includes these summaries from prior calls with the same candidate in its context. This allows the AI to reference previous conversations, avoid re-asking questions, and pick up where a prior call left off.

## Call Transcripts & Recordings

Every completed call generates a full transcript and optional audio recording.

### Transcripts

Transcripts are available immediately after a call completes and include:

* Speaker labels (Bot / Candidate)
* Timestamps for each turn
* Confidence scores for transcribed responses
* Extracted data highlights

### Recordings

Call recording requires a feature flag to be enabled for your account. Once enabled:

* Recordings are stored securely and linked to the enrollment record
* Recordings are retained according to your company's data retention policy
* Candidates are informed at the start of the call that the conversation is being recorded

Even without the feature flag, you can enable recording for individual test calls to review bot behaviour before going live.

## Analytics & Reporting

The AI Caller dashboard provides real-time visibility into call performance.

### Key Metrics

| Metric                 | Description                                           |
| ---------------------- | ----------------------------------------------------- |
| **Connection Rate**    | Percentage of calls answered by candidates            |
| **Completion Rate**    | Percentage of answered calls that reach the closing   |
| **Avg. Call Duration** | Average length of completed calls                     |
| **Data Capture Rate**  | Percentage of form fields successfully populated      |
| **Retry Rate**         | Percentage of enrollments requiring multiple attempts |
| **Drop-off Point**     | Where in the script candidates most often hang up     |

### Monitoring

Use the dashboard to:

* Track active enrollments and their statuses in real time
* Identify scripts with low completion rates and optimize them
* Compare performance across different caller bots
* Monitor telephony provider health and call quality

## Integration with Automations

AI Caller integrates seamlessly with the [Automations](/features/automations) system.

### Triggering Enrollments via Automation

Automatically enroll candidates in a caller bot when:

* A candidate enters a specific stage
* A form is submitted
* A compliance rule passes or fails
* On a scheduled basis (e.g., daily at 10 AM)

**Example automation:**

```
Trigger: Application enters "Phone Screen" stage
Rule: Candidate has a valid phone number
Action: Enroll in "Warehouse Pre-Screen" caller bot
```

### Triggering Automations from Call Results

Use call outcomes to drive downstream workflows:

| Call Outcome                             | Automation Action                        |
| ---------------------------------------- | ---------------------------------------- |
| Call completed, all questions answered   | Advance candidate to next stage          |
| Call completed, candidate not interested | Update application status to "Withdrawn" |
| Call failed after max retries            | Send SMS with callback instructions      |
| Candidate flagged for review             | Notify hiring manager via Slack          |

## Use Cases

* **Pre-Screening** - Conduct initial phone screenings to verify candidate interest, availability, and basic qualifications before scheduling in-person interviews.

  * **Document Follow-Up** - Call candidates who haven't submitted required documents to remind them and collect missing information.

  * **Scheduling** - Confirm interview times, collect availability preferences, and schedule appointments.

  * **Onboarding Check-Ins** - Make welcome calls to new hires and collect initial onboarding information.

  * **Re-Verification** - Contact employees whose documents are expiring to initiate re-verification and collect updated information.

  * **Survey & Feedback** - Gather post-onboarding feedback or conduct periodic employee satisfaction surveys via automated calls.

## Best Practices

Begin with a short, focused script (3–5 questions). Monitor completion rates and transcript quality, then add complexity. Overly long or complex scripts lead to high drop-off rates.
Don't enroll candidates too early or too late. The best time to call is when the candidate is actively engaged — shortly after they submit an application or enter a new stage.
Respect candidate time zones and avoid calling outside business hours. Calls placed during appropriate hours have significantly higher connection rates.
Outdated information in a knowledge base can lead to incorrect answers during calls. Review and update knowledge base content regularly, especially job descriptions and compensation details.
Review your retry metrics regularly. If most candidates answer on the second attempt, three retries may be sufficient. If connection rates are low, consider adding an SMS nudge before the call.
Periodically read through call transcripts to ensure the AI is handling conversations well. Look for misunderstood questions, awkward phrasing, or missed follow-ups and adjust the script accordingly.