Skip to main content

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.

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 →

​
Adding the Phone channel

1

Add Channel → Phone

Pick the workspace phone number you want to bind.
2

Choose voice and language

FieldNotes
VoiceTTS voice (e.g. alloy). Test a few to find one that fits your brand.
LanguageLocale code (en-US, en-GB, etc.).
3

Save and Deploy

Inbound calls to the bound number now reach the flow. Outbound becomes available from the toolbar.

​
Inbound: how a call lands in the flow

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:
1

Click Start Conversation

Pick the Phone channel.
2

Enter the callee's number

E.164 format (+15551234567).
3

Set initial parameters

Anything the first actor needs — customer_name, account_id, reason_for_call, etc.
4

Click Start

The platform places the call. When the callee picks up, the first actor speaks the opener.
Read more: Start a 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

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.”
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.
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.

​
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 here.

​
Next

Deploy a flow

Schedule the phone listener.

Start a conversation

Place an outbound call.