Voice Channel (Phone)

Connecting Voice

The Voice channel uses Vapi to handle phone calls. Vapi manages the telephony layer (STT → LLM → TTS) while your agent provides the intelligence.

Step 1: Create a Vapi Account

1. Go to vapi.ai and create an account
2. In the Vapi dashboard, navigate to Dashboard → API Keys
3. Copy your API key — you'll need it when connecting in Communa

Step 2: Add a Phone Number in Vapi

You need a phone number for callers to reach your agent:

1. In the Vapi dashboard, go to Phone Numbers
2. Click Add Phone Number
3. Choose a provider — Vapi offers built-in numbers, or you can connect your own via Twilio or Vonage
4. Follow the prompts to provision a number

Step 3: Connect in Communa

1. Go to your agent → Channels
2. Click Connect Channel → select Voice
3. Paste your Vapi API key, then click Validate & Load Numbers
4. Select one of the phone numbers loaded from your Vapi account
5. Click Connect Voice

Communa automatically registers the webhook on the selected Vapi phone number — no manual webhook configuration is needed. After connecting, open Settings → Voice to configure the greeting, transcription language, conversation model, context, instructions, and call experience.

Test Your Connection

Call the phone number shown on your connection card. Your agent should pick up, speak the greeting message, and be ready to converse.

---

How It Works

The Voice channel combines a low-latency conversation model with your full Communa agent:

1. The caller speaks and Vapi transcribes the audio to text (STT)
2. The selected conversation model handles turn-taking and direct conversational replies
3. Vapi converts the reply to speech (TTS) and plays it to the caller
4. When the caller asks the agent to do something — such as check email, run a script, or look up data — the conversation model invokes the agent_action tool
5. Your full Communa agent runs the action with its configured Chat model, tools, skills, credentials, and context, then returns the result to the call

The Voice conversation model is therefore not a replacement for the agent's Chat model. It keeps the call responsive and routes operational work to the full agent backend.

---

Model Options

Choose which LLM powers the voice conversation. Communa exposes a curated set of Vapi models verified for the managed STT → LLM → TTS flow and tool calling. Realtime, experimental, regional, and duplicate alias IDs are intentionally hidden.

OpenAI

Anthropic

Google

---

Voice Settings

After connecting the channel, open Settings → Voice. The settings are organized into three focused tabs, and one Save action persists the complete Voice configuration.

General

• Greeting message — The first thing callers hear. Leave it empty to use a dynamic greeting that includes the caller's name when available.
• Transcription language — Optimizes speech recognition for the primary language callers use.
• Maximum call duration — Sets a limit from 1 minute to 2 hours; the default is 30 minutes.

Behavior

• Conversation model — Selects the low-latency model that handles turn-taking and conversational replies. Tool-backed work still runs through the full agent and its configured Chat model.
• Conversation context — Controls which history the agent can use during a call.
• Voice processing instructions — Defines call-specific tone, interaction style, confirmation rules, scripts, and language preferences.

Communa automatically adds spoken-output guardrails for TTS, including concise speech-friendly formatting. You do not need to duplicate those rules in your Voice processing instructions.

Conversation Context Modes

Experience

• Conversation pace — Choose Responsive, Balanced, or Patient. Balanced is recommended for most agents.
• While the agent works — Customize the immediate acknowledgment, up to five progressively timed updates, and the failure message spoken during an agent action.
• Caller silence — Optionally ask whether an inactive caller is still there, then end abandoned calls after a separate silence limit.
• Call recording — Enable or disable Vapi recording for this agent.

Waiting messages and caller-silence messages solve different problems. Waiting messages play while an agent action is running; silence messages re-engage a caller who has stopped speaking. Waiting-message delays are elapsed milestones rather than repeating intervals.

Reset to Defaults

Use Reset in Behavior to restore the recommended Voice processing instructions. In Experience, use Reset recommended defaults to restore pacing, progress messages, silence handling, and recording defaults.

---

Features

Auto-Wake

When your agent is sleeping and a call comes in:

1. The computer is automatically started — no dashboard visit needed
2. The greeting message plays while the computer warms up
3. The agent is ready to handle the call with full capabilities

This means your agent is effectively always reachable by phone, even when its computer is shut down to save resources.

Greeting Message

The first thing callers hear when the call connects. Configure it in the agent's Voice settings. If left empty, Communa uses a dynamic greeting that includes the caller's name when available.

Speech-to-Text (STT)

Powered by Deepgram Nova-3. Configure the primary language under Settings → Voice → General:

• English (default), Hebrew, Spanish, French, German, Arabic, and many more
• Language selection optimizes recognition accuracy for the primary spoken language
• The agent itself can respond in any language based on its instructions

Text-to-Speech (TTS)

The current Communa integration uses OpenAI Alloy — a natural, conversational voice. A dedicated provider-backed voice selector and audio preview are planned separately; voice identity is not yet configurable from the agent settings UI.

Call Duration

Default maximum: 30 minutes per call. Configure it in the agent's Voice settings. After the maximum duration, the call ends gracefully.

Call Recording

Enabled by default and configurable under Settings → Voice → Experience. Call recordings are captured by Vapi and can support quality assurance and training. You are responsible for consent, disclosure, retention, and access requirements in every jurisdiction where the agent operates.

End-Call Function

The agent can hang up the call when appropriate — for example, after saying goodbye or when the caller's needs are fully addressed. This is handled automatically by Vapi's end-call function.

Silence Handling

By default, sustained caller silence ends the call after 30 seconds. You can change this limit and optionally add a caller check-in such as “Are you still there?” Keep enough time between the final check-in and the hard cutoff so the caller can respond.

---

How Voice Differs from Text Channels

---

Tips & Best Practices

• Choose the right model — GPT-4o is a great default. For simpler use cases, GPT-4o Mini offers faster responses at lower cost.
• Test your greeting message — Call your agent and listen to the first impression. A good greeting sets the tone for the entire call.
• Keep voice instructions focused — Unlike text chat, callers can't scroll back. Instruct your agent to be concise and confirm understanding.
• Acknowledge long actions — Keep a short initial acknowledgment and progressively spaced waiting updates so callers know the agent is still working.
• Start with Balanced pacing — Move to Responsive only when speed matters more than accommodating natural pauses; use Patient for callers who pause while recalling details.
• Set the right STT language — If your callers primarily speak a non-English language, set the STT language accordingly for better recognition accuracy.
• Combine with other channels — An agent can handle phone calls during business hours and process Telegram/WhatsApp messages anytime. Use the voice channel for high-touch interactions and text channels for async communication.
• Monitor from the dashboard — While a call is in progress, you can observe the agent's actions in the dashboard chat in real time.

What's Next?

• Channels Overview — Shared channel features, auto-wake, and connection management
• Telegram Channel — Connect your agent via Telegram
• WhatsApp Channel — Connect your agent via WhatsApp
• Chat & Computer — The dashboard workspace for direct agent interaction