Build Voice Assistants: Inbound and Outbound Calls

Feather’s voice layer lets you deploy AI assistants that speak and listen over real phone lines or directly in the browser. From a quick browser call to a production line with warm transfer to your support team, the same assistant configuration powers it all. Voice conversations are fully transcribed, evaluated, and stored alongside your text conversations.

Prerequisites

Voice features require a connected Twilio integration to provision phone numbers and place calls. Follow the Connect an Integration guide to set up Twilio first. You’ll also need at least one registered phone number (covered below).

Choose a voice

Browse the available voices and audition them with their preview URLs:

curl "https://api-sandbox.featherhq.com/v1/voice/voices" \
  -H "x-api-key: <your_api_key>"

Voices come from ElevenLabs and Inworld. List the available synthesis and transcription models with GET /v1/voice/tts-models and GET /v1/voice/stt-models. Once you’ve chosen a voice_id, create a pipeline config.

Create a voice pipeline config

A voice pipeline config controls how your assistant sounds — which voice it uses, the STT engine, language, and the opening greeting. Attach it to exactly one owner: an assistant (agent_id), a team_id, or a persona_id.

curl -X POST https://api-sandbox.featherhq.com/v1/voice/configs \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "<voice_uuid>",
    "agent_id": "<agent_id>",
    "stt_provider": "deepgram",
    "language": "en",
    "first_speaker": "agent",
    "mode": "static",
    "text": "Hello, thanks for calling. How can I help you today?"
  }'

Response

{
  "id": "vconf_01hxbz9k2mr4pn3q7wes",
  "voice_id": "<voice_uuid>",
  "agent_id": "<agent_id>",
  "stt_provider": "deepgram",
  "language": "en",
  "first_speaking_config": {
    "first_speaker": "agent",
    "mode": "static",
    "text": "Hello, thanks for calling. How can I help you today?",
    "interruptible": true,
    "ai_disclosure_text": null
  },
  "created_at": "2026-09-01T10:00:00Z"
}

Field	Description
`voice_id`	The voice to synthesize with (required)
`stt_provider`	Speech-to-text engine: `inworld` (default), `deepgram`, or `elevenlabs`
`first_speaker`	`"agent"` to have the assistant speak first; `"user"` to wait for the caller
`mode`	`"static"` uses the fixed `text` greeting; `"dynamic"` lets the assistant generate its opener

The greeting fields (first_speaker, mode, text) are returned nested under first_speaking_config — they live on the assistant’s revision. For a reusable config you can share across assistants, use /v1/voice/saved-configs and link it with PUT /v1/voice/assistants/{agent_id}/voice-config-source.

Tune call behavior

Interruptions, silence handling, voicemail detection, DTMF, and background audio are configured on call-settings, separate from the pipeline config. Each owner has its own call-settings resource:

GET/PATCH /v1/assistants/{agent_id}/revisions/{revision_id}/call-settings
GET/PATCH /v1/teams/{team_id}/call-settings
GET/PATCH /v1/personas/{persona_id}/call-settings

curl -X PATCH \
  https://api-sandbox.featherhq.com/v1/assistants/<agent_id>/revisions/<revision_id>/call-settings \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "interruptions_enabled": true,
    "silence_timeout_ms": 8000,
    "voicemail_detection_mode": "leave_message",
    "voicemail_message": "Hi, this is a courtesy call from Acme — we will try again later.",
    "recording_enabled": true
  }'

Notable fields: interruptions_enabled (and thresholds like interruption_min_words), silence_timeout_ms / silence_reminder_count, voicemail_detection_mode (off or leave_message), dtmf_enabled, background_audio_preset, recording_enabled, and transcription_storage_enabled.

Audio recording and privacy

Whether call audio is retained — and in what form — is an organization-wide setting on the privacy config, distinct from the per-assistant recording_enabled capture toggle. Set it with PUT /v1/privacy/config:

curl -X PUT https://api-sandbox.featherhq.com/v1/privacy/config \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_retention_policy": "redacted",
    "audio_redaction_fill": "tone_1khz",
    "pii_scrubbing_enabled": true
  }'

`audio_retention_policy`	Behavior
`no_audio`	No recording is captured or stored. Playback is unavailable.
`raw`	Full audio is stored and playable after the call finalizes.
`redacted`	Audio is stored with PII spans muted (filled with silence or a 1 kHz tone). Playback is blocked until the redaction pass succeeds.

redacted requires PII scrubbing to be enabled with at least one detector — Feather rejects the config otherwise. The policy is pinned at capture time, so changing it later does not retroactively expose or redact existing recordings.

Fetch a time-limited playback URL for a stored recording with GET /v1/voice/recordings/{recording_id}/playback-url. See Privacy & Data Protection for the full PII and retention model.

Register a phone number

To receive or place calls on a real number, register it with Feather and bind it to an assistant.

curl -X POST https://api-sandbox.featherhq.com/v1/communication/phone-numbers \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_e164": "+15555550100",
    "vendor": "twilio",
    "vendor_mode": "byo",
    "capabilities": ["voice", "sms"]
  }'

vendor_mode: "byo" means Bring Your Own — the number is already provisioned in your Twilio account. The response returns the phone number id with status: "active".

Bind an assistant to the number

Create an inbound channel so calls to this number route to your assistant automatically.

curl -X POST \
  "https://api-sandbox.featherhq.com/v1/communication/phone-numbers/<phone_number_id>/channels" \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "channel_type": "inbound_call", "agent_id": "<agent_id>" }'

Your number now routes directly to the assistant. Call it to test.

Place an outbound call

Programmatically dial a customer from a registered number.

curl -X POST https://api-sandbox.featherhq.com/v1/voice/outbound \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "from_phone_number_id": "<phone_number_id>",
    "to_phone_number": "+15555550123",
    "agent_id": "<agent_id>"
  }'

Response

{
  "queued": true,
  "room_name": "feather-room-0hxc3n4mr7qp5s9ydfh",
  "dispatch_id": "disp_01hxc3n4mr7qp5s9ydfh",
  "session_id": "ses_01hxc3p5nr8qr6t0zegj"
}

Use the session_id to look up the transcript and evaluation results after the call ends. You can pause, resume, or cancel outbound dispatch with POST /v1/voice/outbound/pause · /resume · /cancel, and restrict calling to business hours with GET/PUT /v1/voice/call-window.

Start a web call (browser testing)

Test your voice assistant in a browser without a phone number. Feather creates a LiveKit room and returns credentials for the LiveKit client SDK.

curl -X POST https://api-sandbox.featherhq.com/v1/voice/web-call \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "<agent_id>" }'

Response

{
  "livekit_url": "wss://feather.livekit.cloud",
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "room_name": "feather-room-0hxc3n4mr7qp5s9ydfh",
  "session_id": "ses_01hxc3p5nr8qr6t0zegj"
}

Connect from your frontend:

import { Room } from "livekit-client";

const room = new Room();
await room.connect("<livekit_url>", "<access_token>");
await room.localParticipant.setMicrophoneEnabled(true); // start speaking

Warm call transfer

A warm transfer puts the customer on a brief hold, dials a human supervisor in the background, briefs them, and then bridges the two together — so the operator is never caught off guard.

Bridge numbers are the dedicated lines Feather uses to conference the two parties. Import one at the org level using its Twilio SID.

curl -X POST https://api-sandbox.featherhq.com/v1/identity/org/bridge-numbers \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "twilio_number_sid": "<PN...>", "integration_connection_id": "<conn_id>" }'

Define a transfer destination

Configure the destination as a call_transfer tool (POST /v1/tools with tool_type: "call_transfer") with a static E.164 destination or a dynamic destination resolved from an API tool. Attach it to your assistant revision like any other tool.

Let the assistant transfer in-call

When a transfer is warranted, the assistant triggers it in-call via the transfer_call platform tool or a workflow handoff node. In warm mode, Feather holds the caller, dials the supervisor on the bridge line, plays an AI briefing they can accept or decline, and then conferences both parties. Inspect what happened with GET /v1/voice/warm-transfer/{conversation_id}/transfer-detail.

If the supervisor leg never connects, the attempt lands in the failed-transfer inbox (GET /v1/hitl/failed-transfers) so you can follow up.

Get Started

Core Concepts

Guides

Channels

Build Voice Assistants: Inbound and Outbound Calls

Prerequisites

Choose a voice

Create a voice pipeline config

Tune call behavior

Audio recording and privacy

Register a phone number

Place an outbound call

Start a web call (browser testing)

Warm call transfer

Next steps

Privacy & data protection

Voice API reference

​Prerequisites

​Choose a voice

​Create a voice pipeline config

​Tune call behavior

​Audio recording and privacy

​Register a phone number

​Place an outbound call

​Start a web call (browser testing)

​Warm call transfer

​Next steps

Privacy & data protection

Voice API reference

Prerequisites

Choose a voice

Create a voice pipeline config

Tune call behavior

Audio recording and privacy

Register a phone number

Place an outbound call

Start a web call (browser testing)

Warm call transfer

Next steps