Phone Calls

VoiceStudio can place and receive phone calls using your own Twilio number, speaking in your cloned or designed voice. Running speech synthesis, speech recognition, and optional local Large Language Models (LLMs) on your computer ensures calls remain private and controlled.

Connecting Twilio#

To enable phone calls, you need a Twilio account with a voice-enabled phone number. Setup is completed via the Integrations → Twilio page.

1. Twilio Credentials#

Enter your Account SID and Auth Token from your Twilio Console. VoiceStudio encrypts your Auth Token locally. It is never returned by the API, logged, or included in exports.

2. Public HTTPS Tunnel#

Twilio requires a public HTTPS URL to communicate with VoiceStudio. Setup a tunnel using cloudflared or ngrok pointing to port 3950 (the default port of the separate call gateway):

cloudflared tunnel --url http://127.0.0.1:3950
# or
ngrok http 127.0.0.1:3950

Paste your public HTTPS URL (for example, https://your-subdomain.trycloudflare.com) into the Public tunnel URL field and save. Do not include a path.

3. Configure Twilio Webhook#

In your Twilio Console, open Phone Numbers → Manage → Active numbers, select your number, and locate the Voice configuration section. Set A call comes in to Webhook, paste your voice webhook URL (https://<your-tunnel>/integrations/twilio/voice), and select HTTP POST.

Call Security & Guardrails#

VoiceStudio enforces strict safety and privacy measures for all telephone interactions:

• Voice Restrictions: Outbound agents can only use designed voices (see Voice Design) or cloned voices where you have verified ownership by recording a consent statement (see Voice Cloning & Gallery). Cloned voices of others cannot place calls.
• Financial & ID Protection: The agent is hardcoded to never provide passwords, bank accounts, card details, or government IDs. An automatic sentence filter blocks any speech containing card numbers or non-brief numbers of 9 or more digits.
• Signed Request Verification: Every webhook request must have a valid X-Twilio-Signature matching your Auth Token. To prevent signature abuse, requests are throttled after 10 signature failures within a minute.
• WebSocket Security: Media streams do not sign connection requests. VoiceStudio generates a random, single-use token valid for 60 seconds. The stream is rejected if the token is missing or expired.
• No Automatic Queuing: Calls are never dialled automatically or in bulk. Only one outbound or inbound agent call runs at a time by default (configurable up to two).
• Call Recordings: Recording is disabled by default. If enabled under settings, VoiceStudio still requires the call's disclosure phrase to explicitly mention that the call is being recorded (e.g., "This call is recorded"). If no such phrase is present, recording remains inactive. Recordings are saved as stereo WAV files in your local data folder.

Placing Outbound Calls#

You can design call drafts in the canvas workspace (see Workflows & Batch Jobs) or place them directly from the Calls interface.

To place a call, provide:

1. Phone Number: Full international format (e.g., +1 555 010 0199).
2. What should it do?: A task brief detailing names, times, goals, and acceptable fallbacks.
3. Voice: A designed voice or verified clone.
4. AI Disclosure: A notice identifying the caller as an AI assistant. While customizable or removable, the agent will always state truthfully that it is an AI if asked.
5. Maximum Length: By default, calls end after 10 minutes (configurable up to 30 minutes).

Live Monitoring and Control#

When a call connects, you can monitor its progress in real-time:

• Timeline: Tracks call states from Dialing and Ringing to In call and Ended.
• Agent State: Visualizes whether the agent is listening, thinking, or speaking.
• Live Transcript: Fills in text turn-by-turn as both parties speak.
• Barge-in Support: If the other person speaks over the agent, VoiceStudio immediately interrupts its synthesis, sends a clear command to Twilio, and listens.
• Take Over: Pause the AI agent's replies. You can type manual responses, which are read aloud in the agent's voice.
• Hang Up: Immediately terminates the call.

Call Outcomes#

After the call closes, the agent generates a summary and assigns one of these outcomes:

• booked: The reservation or appointment was secured.
• done: The task was successfully completed.
• not_done: The task could not be completed.
• needs_you: The agent escalated the call because it encountered questions not covered in the brief.
• failed: An error occurred (e.g., connection lost or number busy).

Handling Incoming Calls#

In call settings, you can configure how VoiceStudio handles incoming calls to your Twilio number:

• Greeting Mode (Default): Plays a customized greeting text (up to 1,000 characters) and hangs up.
• AI Agent Mode: Connects the caller to an interactive AI agent using a custom incoming-call brief (e.g., "Take a message: ask who is calling and what it is about"). It uses the voice, engine, and language defined in your Twilio settings.

You can preview the sound of your greeting exactly as a caller would hear it by clicking Play phone-quality preview. This resamples the greeting to 8 kHz µ-law, tests your synthesis engine locally, and pre-warms the cache so incoming calls are answered instantly.

Telephony Limits & Environment Variables#

You can customize gateway settings and resource consumption with the following environment variables:

Docker Setup#

When running inside a Docker container, the telephony listener binds to loopback (127.0.0.1). If your tunnel runs in another container or on the host machine, you must expose the gateway by setting:

OMNIVOICE_TWILIO_HOST=0.0.0.0

Publish the port to the host (for example, -p 127.0.0.1:3950:3950). Publish it only to your tunnel interface, never to your LAN or the internet directly.

Local Telephony API#

The telephony and calls systems expose local endpoints for configuration and session management. All routes are authenticated and restricted to administrators.