Create a new call

Authorizations

Authorization

string

header

required

Use Authorization: Bearer tc_live_xxxxx

Headers

Idempotency-Key

string

Optional client-supplied idempotency key. When present, the gateway caches the response for 24 hours and returns the same response on retried requests with the same key (account-scoped). Safe for retries on network blips. Format: 8-255 ASCII characters from [A-Za-z0-9_-].

Required string length: 8 - 255

Pattern: ^[A-Za-z0-9_-]+$

Example:

"a1b2c3d4-e5f6-7890-abcd-ef0123456789"

Body

application/json

Option 1
Option 2
Option 3

phone_number

string

required

Phone number in E.164 format (e.g., +14155551234)

Must start with +
Country code must be 1-9 (not 0)
Total length: 1-15 digits after the +
Also validated as dialable; country codes that don't exist are rejected

Pattern: ^\+[1-9]\d{1,14}$

Example:

"+14155551234"

task

string

required

Simple prompt describing what the AI should do. Direct calls need at least one of task or instructions (both may be supplied). Not required for campaign execution (config comes from the campaign).

Minimum string length: 10

Example:

"Call to confirm John's appointment tomorrow at 3 PM"

from_number

string

Caller ID in E.164 format (optional, falls back to FROM_NUMBER env var)

Must be in E.164 format if provided
Either provide this or set FROM_NUMBER environment variable

Pattern: ^\+[1-9]\d{1,14}$

Example:

"+18005551234"

first_sentence

string

The AI's opening line

Minimum string length: 1

Example:

"Hi, this is Rachel from TopView Dental calling about your appointment."

first_sentence_delay_seconds

integer

default:0

How long the agent waits after the call is answered before speaking its opening line. 0 (the default) speaks immediately.

Use a short hold when the people you call tend to need a moment to get the handset to their ear, since the opening words are otherwise lost. The wait is part of the connected call and is billed as talk time.

With first_sentence_wait_for_caller set, this stops being a fixed pause and becomes the longest the agent stays silent before speaking anyway.

Required range: 0 <= x <= 10

Example:

2

first_sentence_wait_for_caller

boolean

default:false

Let the person you called open the conversation. The agent stays silent until they speak, then delivers the opening line as its reply. What they said is kept in the transcript and given to the model as context; it is not answered separately.

Requires first_sentence_delay_seconds of at least 1, which bounds the silence when nobody says anything.

Example:

false

instructions

string

Full system instructions for the AI. Direct calls need at least one of task or instructions (both may be supplied). Not required for campaign execution (config comes from the campaign).

Minimum string length: 10

Example:

"You are Rachel, a friendly appointment coordinator..."

mode

enum<string>

default:realtime

Conversation mode

realtime: Speech-to-speech mode (low latency)
legacy: Separate STT → LLM → TTS pipeline (custom voices, voice cloning)

Available options:

realtime,

legacy

voice

string

default:alloy

Voice to use for AI responses.

Realtime mode:

Available voices: alloy, echo, shimmer, ash, ballad, coral, sage, verse

Legacy mode (custom voices):

Voice names: rachel, domi, bella, antoni, elli, josh, arnold, sam, adam, nicole, matilda
Or voice_id directly: 21m00Tcm4TlvDq8ikWAM (24-char alphanumeric)
Custom/cloned voices: Use the voice_id from your account

Legacy mode (fast voices):

Expressive low-latency voices: leo, luca, francesca, mirella, and others listed under GET /v1/voices/builtin

Minimum string length: 1

Example:

"alloy"

model

string

AI model to use for the call. Default is selected based on mode.

See GET /v1/models for the complete list of available models and their capabilities.

Defaults are automatically selected per mode if not specified.

Minimum string length: 1

temperature

number

default:0.7

LLM creativity/temperature (0-1). Higher values = more creative responses.

Check supports_temperature on the chosen model in GET /v1/models. Models that report false run at the provider default and ignore whatever you send here.

Required range: 0 <= x <= 1

stt_provider

enum<string>

default:deepgram

Speech-to-text engine (legacy mode only). Send one of the enum values. Capabilities, language lists, and knobs for each engine are on GET /v1/models. Only used when mode=legacy.

Available options:

deepgram,

gladia,

speechmatics,

soniox

Example:

"deepgram"

stt_model

string

default:nova-3

STT model (legacy mode only). See GET /v1/models for complete list of available STT models and their capabilities. Only used when mode=legacy.

Minimum string length: 1

Example:

"nova-3"

stt_language

string

STT language code (legacy mode only). Which codes are valid depends on the selected engine; see GET /v1/models for the list on each STT model. Some engines accept regional variants (en-US); others accept only ISO 639-1 base codes (en). The value multi is a multilingual sentinel on engines that advertise it. For a restricted detection set, use stt_languages instead. Only used when mode=legacy.

Required string length: 2 - 35

Example:

"en-US"

stt_languages

string[]

Array of language codes for restricted multi-language detection (supported on select transcription engines).

When multiple languages are provided:

Enables code_switching mode automatically
Restricts detection to ONLY these specified languages
Dramatically improves accuracy for short phrases

Narrows the detection space from 99 languages to just the ones you specify. Omit this field (or send an empty array) for unrestricted multilingual auto-detection.

Must be ISO 639-1 base codes only - regional variants like en-US or zh-CN are not accepted for restricted detection. See GET /v1/models for the full list.

Examples:

["en", "ro"] - Detect English and Romanian only
["en", "es", "fr"] - Detect English, Spanish, and French
["en", "ar", "hi"] - Detect English, Arabic, and Hindi

Only used when mode=legacy. Honour depends on the selected STT engine; see GET /v1/models.

Required array length: 1 - 10 elements

Minimum string length: 2

Example:

["en", "ro"]

stt_vocabulary

(string | object)[]

Custom vocabulary for STT (multi-language provider only). Boost recognition of domain-specific words and phrases in real time.

Formats supported:

Simple strings: ["Capex", "TopCalls"]
Objects with language: [{"value": "Capex", "language": "en"}]
Mixed: ["Capex", {"value": "مرحبا", "language": "ar"}]

Use cases:

Company/product names
Industry-specific terminology
Names that may be mispronounced
Technical terms

Only used in legacy mode with the multi-language STT provider.

Required array length: 1 - 100 elements

Minimum string length: 1

Example:

[
  "Capex",
  { "value": "TopCalls", "language": "en" }
]

stt_endpoint_sensitivity

number

default:0.01

Endpoint delay: seconds to wait after the caller stops speaking before finalizing the turn. (The field is named stt_endpoint_sensitivity for backward compatibility, but it controls a wait time, not a sensitivity bias.)

Effective range depends on the selected STT engine (see GET /v1/models for min/max/default on each model). Lower values end turns faster; higher values wait longer for pauses. Values outside the active engine's range may be clamped or rejected. Only used in legacy mode. Engines that do not expose this knob accept the field and ignore it.

Required range: 0.01 <= x <= 3

Example:

0.01

stt_endpoint_eagerness

number

default:-0.3

Semantic endpoint-sensitivity bias (−1 to 1). Distinct from stt_endpoint_sensitivity, which is a delay in seconds: this is a unitless bias score that nudges the decision about whether the caller has finished a turn.

Negative values (e.g. −0.5): wait longer before ending the turn, reducing mid-sentence cut-offs on slow or thoughtful callers.
Positive values (e.g. 0.5): end turns more eagerly, snappier hand-off back to the agent.
Default: −0.3 (slightly more patient than the neutral 0).

Only honoured by STT engines that advertise this knob on GET /v1/models. Ignored by others.

Required range: -1 <= x <= 1

Example:

-0.3

stt_interrupt_sensitivity

number

default:0.8

STT interrupt/speech detection sensitivity (multi-language provider only). Controls the speech detection threshold for distinguishing speech from noise.

Range: 0.0 - 1.0
Default: 0.8 (recommended for telephony audio)
Higher values (0.7-0.9): Recommended for telephony audio, background noise
Lower values (0.0-0.4): More sensitive to speech, may pick up more noise

Only used in legacy mode with the multi-language STT provider.

Required range: 0 <= x <= 1

Example:

0.8

stt_max_delay

number

default:1.5

Max wait in seconds before finalizing a transcript (supported on select transcription engines). Lower = snappier turn-ends, higher = more patience for slow speakers.

Range: 0.7 - 4.0 seconds
Default: 1.5 seconds
Fixed platform-wide for other providers.

Only used in legacy mode. Accepted but ignored unless the selected STT engine advertises this knob on GET /v1/models.

Required range: 0.7 <= x <= 4

Example:

1.5

transcript_correction_vocabulary

(string | object)[]

Transcript correction vocabulary for LLM-based STT error correction (legacy mode only). Provides domain-specific terms that STT often mishears, allowing the LLM to use context to mentally correct transcription errors.

Formats supported:

Simple strings: ["Weaviate", "Kubernetes", "TopCalls"]

Objects with sounds_like hints:

[
  { "correct": "Weaviate", "sounds_like": ["we activate", "web VT"] },
  { "correct": "NVIDIA", "sounds_like": ["in video"], "context": "hardware" }
]

Mixed: ["TopCalls", { "correct": "Kubernetes", "sounds_like": ["cube net ease"] }]

How it works:

The vocabulary is added to the LLM system prompt
When STT mishears a domain term, the LLM uses context to interpret correctly
No additional latency (processed in the main LLM call)
LLM responds naturally without mentioning the correction

Use cases:

Company/product names (Weaviate, Kubernetes, NVIDIA)
Industry-specific terminology (medical, legal, financial terms)
Technical terms that sound like common words
Names that may be mispronounced

Only used when mode=legacy.

Required array length: 1 - 100 elements

Minimum string length: 1

Example:

[
  "TopCalls",
  {
    "correct": "Weaviate",
    "sounds_like": ["we activate", "web VT"]
  },
  {
    "correct": "Kubernetes",
    "sounds_like": ["cube net ease", "cooper nettie"],
    "context": "technology"
  }
]

tts_provider

enum<string>

default:cartesia

TTS provider (legacy mode only). See GET /v1/voices/builtin for available voices per provider. Only used when mode=legacy.

Available options:

elevenlabs,

cartesia

Example:

"cartesia"

tts_model

string

TTS model (legacy mode only). See GET /v1/models for complete list of available TTS models. Only used when mode=legacy.

Minimum string length: 1

Example:

"eleven_flash_v2_5"

tts_stability

number

Voice stability (legacy mode). Controls the consistency of the voice output.

Lower values (0): More variable, emotional, expressive
Higher values (1): More consistent, stable, less expressive
Default: 0.75 (optimized for voice agents)
Only used in legacy mode with the corresponding TTS provider

Required range: 0 <= x <= 1

Example:

0.75

tts_similarity_boost

number

Voice similarity boost (legacy mode). Controls how closely the generated voice matches the original.

Lower values (0): Less similar to original voice
Higher values (1): More similar to original voice
Default: 0.5 (balanced for voice agents)
Only used in legacy mode with the corresponding TTS provider

Required range: 0 <= x <= 1

Example:

0.5

tts_speed

number

Speech speed (legacy mode). Controls the rate of speech.

Lower values: Slower speech; higher values: faster speech
Effective range depends on the selected TTS engine; see GET /v1/models. Values outside that range may be clamped.
Some TTS models speak at a fixed pace and ignore this field.
Only used in legacy mode

Required range: 0.6 <= x <= 1.5

Example:

1.15

tts_style

number

Style exaggeration (legacy mode). Controls expressiveness of the synthesized voice.

Lower values (0): Neutral, no style exaggeration
Higher values (1): Maximum expressiveness
Only some TTS models honour this field; others ignore it. See GET /v1/models.
When omitted, the engine's own default applies
Only used in legacy mode

Required range: 0 <= x <= 1

Example:

0

tts_emotion

string

Baseline emotion for generated speech (legacy mode). Free-form value validated by the selected TTS engine, e.g. enthusiastic, confident, calm. When omitted, a neutral default applies. Accepted but ignored unless the selected engine advertises emotion on GET /v1/models.

Minimum string length: 1

Example:

"enthusiastic"

tts_volume

number

Generated speech volume (legacy mode). 0.5 is quietest, 2 is loudest. When omitted, the engine default applies. Accepted but ignored unless the selected TTS engine advertises volume on GET /v1/models.

Required range: 0.5 <= x <= 2

Example:

1

filler_enabled

boolean

default:false

Enable filler acknowledgments (legacy mode only). When enabled, the AI will generate brief acknowledgments (e.g., "Got it...", "Sure...") before the main response to reduce perceived latency.

false (default): No filler - AI responds directly
true: AI generates contextual filler before main response

Only used when mode=legacy.

Example:

false

emotion_enabled

boolean

default:false

Enable expressive-speech markup (legacy mode, expressive-capable voices only). When enabled, the assistant may add inline prosody and native-language interjections to its spoken text for a more natural delivery.

false (default): plain delivery
true: expressive delivery

Only used when mode=legacy. Accepted but ignored unless the selected TTS engine advertises expressive markup on GET /v1/models.

Example:

false

block_interruption

boolean

default:false

Block interruption mode (legacy mode only). When enabled, the AI continues speaking even if the user talks over it.

User speech during TTS is buffered (not processed immediately)
When TTS ends, buffered speech is merged and checked:
- If ≥5 words: processed through LLM (single call)
- If <5 words: discarded (fillers like "uh huh", "okay")

Use cases:

Delivering critical information that shouldn't be interrupted
Users who provide active listening cues during AI speech
Noisy environments with background speech/noise

Only used when mode=legacy.

Example:

false

bot_protection_enabled

boolean

default:true

Enable bot and spam protection (legacy mode only). When enabled, the system detects automated or non-responsive callers and ends such calls automatically.

true (default): protection active
false: protection disabled for this call

Only used when mode=legacy.

Example:

true

max_duration

integer

default:5

Maximum call duration in minutes (enforced by telephony provider)

Required range: 1 <= x <= 60

background_audio

enum<string>

default:office

Background audio preset to play during the call.

office: Office ambiance (default) - subtle office sounds
none: No background audio

Background audio plays continuously under the conversation and helps create a professional atmosphere.

Available options:

office,

none

Example:

"office"

background_audio_gain

enum<string>

default:medium

Volume level for background audio relative to speech.

low: Subtle (-10 dB) - quieter background
medium: Balanced (-4 dB) - noticeable but balanced (default)
high: Full volume (0 dB) - background at same level as speech

Only used when background_audio is not none.

Available options:

low,

medium,

high

Example:

"medium"

webhook_url

string<uri>

Webhook URL to receive call completion/failure notifications. Webhook is sent after call finishes (includes recording_url and call_summary when available).

Example:

"https://your-app.com/webhooks/call-complete"

webhook_call_status_filter

string[] | null

Restricts which call outcomes fire the webhook_url notification.

Omitted, null, or an empty array: every outcome fires the webhook (default).
Non-empty array: only calls whose final call_status matches a listed value fire the webhook (e.g. ["completed", "failed"]).

Only affects the per-call webhook_url delivery. Account-level webhook subscriptions are configured separately and are not filtered by this field.

Maximum array length: 20

Minimum string length: 1

Example:

["completed", "failed"]

summary_prompt

string

Custom instruction for the post-call summary. When set, the summary included in the webhook payload and call record follows this instruction (e.g. "List the objections raised and the agreed callback time"). When omitted, the platform's default summary style applies.

Required string length: 1 - 5000

Example:

"Summarize the objections raised and the agreed callback time."

analysis_schema

object

Schema for post-call AI analysis. Defines what information to extract from the transcript. After the call, AI analyzes the transcript and extracts structured data matching this schema. Results are included in the webhook payload under the analysis field.

Supported types:

boolean: true/false values (e.g., "converted", "appointment_confirmed")
string/text: Free-form text (e.g., "objections", "questions")
number: Numeric values (e.g., "rating", "call_count")
date: Date/time in ISO 8601 format (e.g., "appointment_time")

Simple format: Just specify the type

{ "converted": "boolean", "objections": "string" }

Rich format: Include description for better AI understanding

{
  "converted": {
    "type": "boolean",
    "description": "Whether the lead agreed to schedule an appointment"
  },
  "appointment_time": {
    "type": "date",
    "description": "The scheduled appointment date/time if booked"
  }
}

Show child attributes

Example:

{
  "converted": {
    "type": "boolean",
    "description": "Whether the lead agreed to schedule an appointment or expressed buying interest"
  },
  "objections": {
    "type": "string",
    "description": "Any concerns or objections the lead raised during the call"
  },
  "appointment_time": {
    "type": "date",
    "description": "The scheduled appointment date and time if one was booked"
  }
}

mcp_url

string<uri>

Optional MCP server URL for remote tool dispatch. When set, the gateway opens an SSE MCP client at call start and merges the remote tools into the LLM tool list.

Example:

"https://integrations.example.com/mcp/abc123"

mcp_tool_allowlist

string[]

Names of MCP tools (as returned by listTools()) that the AI is allowed to invoke during this call. When absent or empty, zero remote MCP tools are attached; only platform tools like end_call remain. Explicit opt-in to prevent prompt bloat from auto-attaching every flow in the connected workspace.

Example:

["book_callback", "send_sms_confirmation"]

tool_call_timeout_ms

integer

default:3000

Per-call timeout for MCP tool invocation in milliseconds. On timeout, the gateway feeds {error: "tool_timeout"} into the second LLM hop so the model can recover conversationally.

Required range: 500 <= x <= 10000

metadata

object

Custom metadata to include in webhook payload. System fields (task, voice, model, etc.) are filtered out automatically.

Example:

{
  "patient_id": "pat_123",
  "source": "reminder_system"
}

lead_id

string<uuid>

Optional lead reference. When provided, the gateway loads the lead record (name, email, notes, status, plus any custom fields stored on the lead) and exposes them to the AI via lead_context. Caller-supplied lead_context takes precedence on key collision. Returns 404 if the lead does not exist in the calling account.

campaign_id

string<uuid>

Optional campaign reference. When provided, the gateway loads the campaign's attached knowledge base and includes it in the call's runtime context. Returns 404 if the campaign does not exist in the calling account.

When used as a campaign execution path (without phone_number), campaign_id, lead_id, idempotency_key, and attempt_number are all required.

attempt_number

integer

Attempt number for campaign execution mode (required when campaign_id is provided without phone_number).

Required range: x >= 1

idempotency_key

string

Idempotency key for campaign execution mode (required when campaign_id is provided without phone_number).

Minimum string length: 8

scheduled_at

string<date-time>

Optional scheduled time for campaign execution mode.

lead_context

object

Free-form key/value context surfaced to the AI during the call. When lead_id is set, the gateway auto-builds a base lead_context from the lead record; any keys passed here shallow-merge on top of the auto-built base and win on collision.

crew

object

Configuration for multiple specialised agents on a single call, with controlled handoffs between them. The first member answers the call; later members take over when their conditions are met. Availability is rolling out gradually.

Show child attributes

Response

Call created successfully

call_id

string<uuid>

Call UUID

Example:

"564d4fd4-03bc-400a-abe0-05540fbeff88"

provider_call_id

string | null

Provider call ID (may be null if call creation failed)

Example:

"64e9bf0e-7c2f-4443-a759-7eb1731cd583"

status

enum<string>

Current call status

Available options:

queued,

pending,

in_progress,

completed,

failed,

cancelled

Example:

"queued"

Overview

Calls

Phone Numbers

Lead lists

Leads

Campaigns

Knowledge Bases

Webhooks

Configuration

Account

Authorizations

Headers

Body

Response