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

# Phone channel

> Inbound and outbound voice calls via Twilio and self-hosted LiveKit SIP. Includes hang-up control from the actor.

The **Phone** channel turns a conversation flow into a real voice agent. Inbound calls land in the flow; outbound calls let you dial out from the editor or a workflow. The actor speaks via TTS; the user speaks naturally; the conversation runs the same way it would in chat.

## When to use Phone

* A receptionist agent that answers inbound calls and routes to the right specialist.
* An outbound sales-development flow that places follow-up calls.
* Voice support for users who prefer talking over typing.
* Multi-leg flows (warm transfer to a human, then back to the AI).

## Before you start

Phone uses **Twilio** for the carrier and **self-hosted LiveKit SIP** for the voice layer. You'll need:

* A Twilio account (or use the shared CogniAgent test number — workspaces get one free claim, time-limited).
* A workspace **phone number** added in **Settings → Phone Numbers**. Either bring your own Twilio number (BYOC) or claim the shared test number.

[Manage workspace phone numbers →](/features/channels)

## Adding the Phone channel

<Steps>
  <Step title="Add Channel → Phone">
    Pick the workspace phone number you want to bind.
  </Step>

  <Step title="Choose voice and language">
    | Field        | Notes                                                                  |
    | ------------ | ---------------------------------------------------------------------- |
    | **Voice**    | TTS voice (e.g. `alloy`). Test a few to find one that fits your brand. |
    | **Language** | Locale code (`en-US`, `en-GB`, etc.).                                  |
  </Step>

  <Step title="Save and Deploy">
    Inbound calls to the bound number now reach the flow. Outbound becomes available from the toolbar.
  </Step>
</Steps>

## Inbound: how a call lands in the flow

```mermaid theme={null}
flowchart LR
    Caller([Caller dials number]) --> Twilio[Twilio trunk]
    Twilio --> LK[LiveKit SIP]
    LK --> Room[Voice room]
    Room --> Agent[Phone-flow worker]
    Agent --> Flow[Conversation flow turn pipeline]
```

The caller hears the first actor speak through TTS. They reply by voice. Speech-to-text runs locally; the actor sees text turns and replies normally. The text is spoken back via TTS.

Most flows feel natural after the first few minutes of tuning the agent's instructions for spoken cadence (shorter sentences, fewer enumerations).

## Outbound: placing a call

In **Initiator** mode:

<Steps>
  <Step title="Click Start Conversation">
    Pick the **Phone** channel.
  </Step>

  <Step title="Enter the callee's number">
    E.164 format (`+15551234567`).
  </Step>

  <Step title="Set initial parameters">
    Anything the first actor needs — `customer_name`, `account_id`, `reason_for_call`, etc.
  </Step>

  <Step title="Click Start">
    The platform places the call. When the callee picks up, the first actor speaks the opener.
  </Step>
</Steps>

[Read more: Start a conversation →](/conversation-flows/operate/start-conversation)

## Hanging up

Voice calls need an explicit "end call" signal that text channels don't. Phone-bound flows expose a special **hang-up tool** that the LLM can call when the conversation is genuinely done.

In the actor's instructions:

```
When the user has confirmed they don't need anything else, say a brief
goodbye and call the hangup tool with reason='completed' and a short
farewell message.
```

The actor speaks the farewell, the platform waits a moment for the audio to finish, then disconnects the call. The conversation is marked **completed** in the history.

## Speech quality tips

<Tip>
  **Shorter sentences.** Long, list-heavy replies sound robotic. Write instructions that nudge the actor toward conversational phrasing — "answer like you would on a phone call, not like a documentation page."
</Tip>

<Tip>
  **Numbers and codes spoken aloud.** Telephone numbers, IDs, and account codes should be split with pauses. "1-2-3-4" reads as "one, two, three, four" — clearer than "twelve-thirty-four". You can prompt this explicitly.
</Tip>

<Warning>
  **Don't quote URLs.** "Visit acme.com/billing" doesn't work on a phone. Have the actor offer to send a text or email follow-up with the link.
</Warning>

## Limits in v1

* **No call recording.** Phone audio isn't stored. Transcripts (text turns) are stored normally.
* **No DTMF input** as a first-class flow trigger. If the user presses keys, the actor doesn't see them.
* **No call transfer to another phone number.** Hand-off is within the flow only.
* **One phone number per flow.** You can have multiple workspace phone numbers, but each binds to one flow.

These limitations apply to the v1 phone channel; some may change. See the latest [phone channel notes](/conversation-flows/channels/phone) here.

## Next

<CardGroup cols={2}>
  <Card title="Deploy a flow" icon="rocket" href="/conversation-flows/operate/deploy">
    Schedule the phone listener.
  </Card>

  <Card title="Start a conversation" icon="paper-plane" href="/conversation-flows/operate/start-conversation">
    Place an outbound call.
  </Card>
</CardGroup>