Skip to main content
POST
Create a call flow

Authorizations

Authorization
string
header
required

A Contact Button scoped bearer key. Send Authorization: Bearer <token>. Token abilities are enforced independently of workspace membership; both checks must pass. OAuth 2.0 authorization-code flows are not currently available.

Headers

Idempotency-Key
string

Stable 8–120 character key for safe mutation retries.

Required string length: 8 - 120

Path Parameters

workspace
string<uuid>
required

Body

application/json
name
string
required
Maximum string length: 120
mode
enum<string>
required
Available options:
ai_agent,
forwarding,
voicemail,
callback
language
string
required
Maximum string length: 16
Example:

"en-US"

tts_voice
string
required
Maximum string length: 120
Example:

"Telnyx.NaturalHD.astra"

max_recording_seconds
integer
required
Required range: 10 <= x <= 300
missed_call_sms_delay_seconds
integer
default:30
required
Required range: 0 <= x <= 3600
provider_assistant_id
string | null

Required for ai_agent mode. Use an assistant ID from the connected Telnyx account.

Maximum string length: 255
forwarding_number
string | null
Pattern: ^\+[1-9][0-9]{7,14}$
caller_id_voice_number_id
integer | null
deprecated

Optional internal compatibility identifier. Omit unless returned by an authorized Contact Button client.

greeting
string | null

Required for voicemail and callback modes.

Maximum string length: 2000
notification_emails
string<email>[]
Maximum array length: 10
notification_phones
string[]
Maximum array length: 10
Pattern: ^\+[1-9][0-9]{7,14}$
fallback_to_voicemail
boolean
default:false
missed_call_sms_enabled
boolean
default:false
missed_call_sms_template
string | null
Maximum string length: 1000
is_active
boolean
default:true

Response

Successful data envelope.

data
any
required
meta
object
required