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

# Phone Integration

> Let your AI agent answer and place phone calls with natural, real-time speech

With a phone line, your AI agent answers calls to your number and calls customers on your behalf. It speaks in real time and full duplex, so callers can interrupt it at any time. It uses the same knowledge, guidance, actions, and procedures as your other channels. Every call shows up as a conversation with recording and transcript.

## How it works

Each call runs on two models. The **speaker model** talks to the caller. It works full duplex: it listens while it speaks, so callers can interrupt it at any time, just like in a conversation with a person. It also handles small talk on its own. Whenever the caller needs an answer from your knowledge or an action, the speaker consults the **thinking model**, which runs your full AI agent: guidance, knowledge, actions, and procedures. The speaker then says the result in its own words.

<img src="https://mintcdn.com/botbrains/VW5KOY20DBGMKYFZ/images/phone/two-models.svg?fit=max&auto=format&n=VW5KOY20DBGMKYFZ&q=85&s=34156b44430d0c8e3632daa32c4bd251" alt="Diagram: the caller talks to the speaker model, which consults the thinking model. Speaker guidance belongs to the speaker model. Guidance, knowledge, actions, and procedures belong to the thinking model." data-generation-prompt="Hand-drawn SVG, edit images/phone/two-models.svg directly. Main row: Caller pill, Speaker model box, Thinking model box, joined by double arrows labeled full-duplex speech and asks and answers. Dashed lines drop from Speaker model to Speaker guidance, and from Thinking model to Guidance, Knowledge, Actions, Procedures." width="900" height="200" data-path="images/phone/two-models.svg" />

Because of this split, you configure each model on its own. A [speaker guidance](#speaker-guidance) controls how the agent sounds, and regular [guidance](/concepts/guidance) controls what it does.

### The full botBrains platform on the phone

On a call, your agent has the full power of the botBrains platform. It answers from the same knowledge, calls your systems, and follows your workflows, just like in chat or email.

<Columns cols={3}>
  <Card title="Knowledge" icon="book-open" href="/concepts/knowledge">
    Answer from your website, documents, and data providers.
  </Card>

  <Card title="Unitools" icon="blocks" href="/concepts/unitools">
    Look up orders, book appointments, and update records in your systems.
  </Card>

  <Card title="Procedures" icon="workflow" href="/concepts/procedures">
    Guide callers through multi-step workflows such as identity checks or cancellations.
  </Card>
</Columns>

## Connect your phone system

Manage your phone line on the [voice integration page](https://platform.botbrains.io/~/integrations?integration=voice). The simplest way to connect is through your botBrains number. Customers call it directly, or you forward your existing number to it in your phone system or with your carrier. On request, botBrains also connects to your phone system directly through SIP.

## Introductions

The agent speaks the introduction word for word before the conversation starts.

In the EU, the opening of a recorded AI call should cover three points:

| Requirement | Source |
| - | - |
| Tell the caller that you record the call | [§201 StGB](https://www.gesetze-im-internet.de/stgb/__201.html) |
| Tell the caller about the recording and give them a way to object, for example with the star key | GDPR [Art. 6](https://gdpr-info.eu/art-6-gdpr/), [Art. 7](https://gdpr-info.eu/art-7-gdpr/), and [Art. 13](https://gdpr-info.eu/art-13-gdpr/) |
| Tell the caller they're speaking with an AI | [EU AI Act Art. 50](https://artificialintelligenceact.eu/article/50/) |

For outbound calls, you know who you call. Instead of the recording notice, you can rely on consent the customer gave before the call, for example in your privacy policy. The AI notice is still required.

The default introductions cover all three points:

```text theme={null}
Guten Tag. Hier ist {agent_name} von {project_name}. Ich bin eine KI. Unser Gespräch wird aufgezeichnet. Drücken Sie jederzeit die Stern-Taste, um dem zu widersprechen. Wie kann ich Ihnen helfen?
```

## Custom words

Custom words improve speech recognition and transcripts. Add names and terms the agent wouldn't recognize otherwise, such as product names, brands, or street names, one per line:

```text theme={null}
botBrains
Kubernetes
Unitools
```

botBrains uses the first 100 entries and the first 50 characters of each. To change how the agent pronounces a word, use a [speaker guidance](#pronunciation) instead.

## Configure the agent for phone

### Speaker guidance

A speaker guidance configures the speaker model. Add it with **Add Speaker Guidance** on the [guidance page](https://platform.botbrains.io/~/profiles). Keep it short and focus on:

* **Speech.** Tone, pace, reply length, how to calm frustrated callers, and how to handle interruptions.
* **Pronunciation.** How to say uncommon words. See [pronunciation](#pronunciation).
* **Immediate knowledge.** Facts the agent can say without looking anything up, such as who you are or your opening hours.

A speaker guidance always applies to calls only, so it can't use actions or select a channel in its audience. Everything that needs a lookup or an action belongs in regular guidance.

### Pronunciation

To control how the agent says a word, write it in the speaker guidance with its pronunciation in IPA (International Phonetic Alphabet) or as a phonetic spelling:

```text theme={null}
Say "Nguyen" as /ŋwiən/.
Say "Worcester" as "WUSS-ter".
Say "n8n" as "en-eight-en".
```

### Phone guidance

Your regular guidance applies on calls too, and the thinking model follows it. To change how the agent speaks, use a [speaker guidance](#speaker-guidance). To give instructions only for calls, scope a guidance with an [audience](/concepts/audiences):

| Audience field | Values |
| - | - |
| `channel.type` | `voice` |
| `channel.voice.direction` | `inbound` or `outbound` |
| `channel.voice.from_number` | The calling number |
| `channel.voice.to_number` | The called number |

### Liquid templating

Like all other guidance, speaker guidance and phone guidance support [Liquid templating](/concepts/guidance#personalize-with-liquid). Every [audience field](/concepts/audiences#available-fields) is available as a variable, including the phone fields above. For example, use it to tell the agent why it calls:

```liquid theme={null}
{% if channel.voice.direction == "outbound" %}
You are calling {{ user.first_name }} about their open support request.
{% else %}
The caller is calling our support line.
{% endif %}
```

For instructions that only apply to inbound or outbound calls, you can also set the `channel.voice.direction` audience on the guidance or speaker guidance instead.

### Phone actions

Enable these [actions](/concepts/actions) on a phone guidance by mentioning them:

| Action | What it does |
| - | - |
| `forward_call` | Transfers the call live to a colleague. See [forwarding and escalations](#forwarding-and-escalations). |
| `handoff` | Hands the request to your team by email. See [forwarding and escalations](#forwarding-and-escalations). |
| `send_sms` | Sends a text message with links, reference numbers, or addresses. If the caller uses a landline, the agent asks for a mobile number first. |
| `end_call` | Hangs up when the caller wants to end the call but can't. Always available. |

Text messages show your project name as the sender, can have up to 459 characters, and can't reach numbers in the US, Canada, or Puerto Rico. Sending text messages incurs additional charges.

## Forwarding and escalations

When a caller needs a person, the agent escalates in one of two ways:

* **Live forward (call transfer).** With `forward_call`, the agent transfers the call to any phone number you list in your guidance, for example your support hotline or a specific team. It picks the number that fits the request, tells the caller where it connects them, and starts the transfer.
* **Email handoff.** With `handoff`, the agent collects the caller's request, name, and email address and sends it to your support email. The caller gets a copy.

A forward is never a dead end. If nobody answers within 30 seconds, the agent takes the conversation back, apologizes, and keeps helping, for example by offering an email handoff instead. When a colleague answers, the agent leaves the call and the conversation counts as [escalated](/concepts/escalations).

Before the transfer rings, the agent saves a short summary of the request on the call. Your contact center can fetch it through the API while the call is live, so your colleague knows what the call is about.

## Outbound calls

Start a call with **Dial** on the [voice integration page](https://platform.botbrains.io/~/integrations?integration=voice). Search for a user with a phone number or type any number. You can also start calls through the API with `POST /projects/{project_id}/voice/{integration_id}/dial` and a `to_number`.

The agent starts talking once a person answers:

* **Voicemail.** If an answering machine picks up, the agent hangs up without leaving a message.
* **iPhone call screening.** A short fixed message introduces your agent and asks to speak with the person. Once the person picks up, the conversation starts.

## How calls end

| Situation | What happens |
| - | - |
| The caller hangs up | The call ends. |
| The caller wants to end the call but can't | The agent says goodbye and hangs up with `end_call`. |
| The caller goes silent | After 30 seconds, the agent asks whether the caller is still there. After 45 seconds, it says the call will end soon. After 60 seconds, it hangs up. |
| The agent forwards the call | The agent leaves once a colleague answers. The call continues without a time limit. |
| The agent talks for 30 minutes | The call ends. |

## Recording and transcripts

Recording and recording opt-out work by default, without any setup. botBrains records every phone call after the introduction. If the caller presses the star key, botBrains stops the recording and discards it. The transcript stays in the conversation either way.

After a forward, botBrains also transcribes the part with your colleague and adds it to the conversation. This makes calls easy to audit, and botBrains learns from how your team answers through [suggestions](/concepts/suggestions).

## Calls

The [calls page](https://platform.botbrains.io/~/calls) lists every call with direction, customer, recording, transcript, and forwarding result. botBrains links each caller to a [user](/concepts/users) by phone number.

<Tip>
  **Only AI time counts.** Voice minutes count the time the AI agent spends on a call, rounded up per started minute. Time with a colleague after a forward is free. See [billing](/concepts/billing).
</Tip>

Every call starts as **In progress** and ends in one of the following statuses. Busy, no answer, voicemail, and undetermined only occur on outbound calls, because botBrains answers every inbound call right away.

```mermaid theme={null}
flowchart LR
    Start(["Call starts"]) --> IP["In progress"]
    IP -->|"ends normally"| C["Completed"]
    IP -->|"error, rejected,<br/>or blocked by a trigger"| F["Failed"]

    subgraph Outbound["Outbound calls only"]
        B["Busy"]
        N["No answer"]
        V["Voicemail"]
        U["Undetermined"]
    end

    IP -->|"line busy"| B
    IP -->|"nobody picks up"| N
    IP -->|"answering machine"| V
    IP -->|"ends before a person<br/>or machine is detected"| U

    style Start fill:#f5f5f5,stroke:#bdbdbd
    style IP fill:#e1f5ff,stroke:#64b5f6
    style C fill:#e8f5e9,stroke:#81c784
    style F fill:#ffebee,stroke:#e57373
    style Outbound fill:#fafafa,stroke:#e0e0e0
    style B fill:#fff4e6,stroke:#ffb74d
    style N fill:#fff4e6,stroke:#ffb74d
    style V fill:#fff4e6,stroke:#ffb74d
    style U fill:#fff4e6,stroke:#ffb74d
```

On voicemail, the agent hangs up without leaving a message. iPhone call screening isn't a status of its own. If the person picks up after screening, the call ends as **Completed**. If they never pick up, it ends as **No answer**, and the calls page shows that the call screening picked up.

## FAQ

<AccordionGroup>
  <Accordion title="Can I keep my existing phone number?">
    Yes. Forward your existing number to your botBrains number, or ask us to connect your phone system through SIP. See [connect your phone system](#connect-your-phone-system).
  </Accordion>

  <Accordion title="How do calls reach my team?">
    The agent forwards calls live (call transfer) to any number you list in your guidance, or hands the request to your team by email. If a colleague doesn't pick up, the agent takes the call back. See [forwarding and escalations](#forwarding-and-escalations).
  </Accordion>

  <Accordion title="Which countries and numbers are supported?">
    You can get a Berlin number quickly and go live with it. For a number from another country, contact us and we provision it for you.
  </Accordion>

  <Accordion title="Where does botBrains store call data?">
    botBrains stores recordings, transcripts, and all other call data in the EU.
  </Accordion>

  <Accordion title="Can I test calls in my browser?">
    Yes. Start a call from the profile preview in your browser. Browser calls skip recording, forwarding, and SMS, and count toward your voice minutes like any other call.
  </Accordion>

  <Accordion title="Can I schedule outbound calls with calling hours, time zones, or retries?">
    Not yet. Phone focuses on inbound calls today. Start outbound calls one at a time with **Dial** or through the API.
  </Accordion>

  <Accordion title="Which number do customers see when the agent calls them?">
    Your botBrains phone number.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.