Configure a voice assistant
Voice assistants (assistant_type: "voice") keep their runtime settings in telnyx_ai_assistant_config. You change them with a normal assistant update; after every create or update the voice agent is synced with the voice provider.
Endpoint
Use the catalog endpoints to pick valid values: voice LLM models, voices and transcription languages.
Request
telnyx_ai_assistant_config is replaced as a whole: send the full object (get the assistant first and change what you need).
Response
The updated AI assistant object (shortened):
json
Voice configuration fields
| Field | Type | Description |
|---|---|---|
acting_user_id | integer | null | User whose identity the assistant uses for write actions during calls. |
telnyx_ai_assistant_config.telnyx_assistant_id | string | null | Read-only in practice. ID of the synced voice agent at the provider. |
telnyx_ai_assistant_config.sync_status | string | null | pending, synced or error. Send pending when you change settings. |
telnyx_ai_assistant_config.last_synced_at | string (date-time) | null | Read-only. Last successful sync. |
telnyx_ai_assistant_config.error_message | string | null | Read-only. Last sync error. |
telnyx_ai_assistant_config.voice_runtime | string | null | telnyx_builtin, custom_llm or openai_realtime_sip. |
telnyx_ai_assistant_config.model | string | null | LLM for the telnyx_builtin runtime, from voice LLM models. |
telnyx_ai_assistant_config.use_custom_llm | boolean | null | Whether the custom LLM runtime is used. |
telnyx_ai_assistant_config.custom_llm_model | string | null | Model used by the custom LLM runtime. |
telnyx_ai_assistant_config.openai_realtime_model | string | null | Model for the openai_realtime_sip runtime. |
telnyx_ai_assistant_config.openai_realtime_voice | string | null | Voice for the openai_realtime_sip runtime. |
telnyx_ai_assistant_config.greeting | string | null | First sentence spoken on the call. |
telnyx_ai_assistant_config.description | string | null | Description sent to the voice provider. |
telnyx_ai_assistant_config.voice_mode | string | null | unified or distinct. |
telnyx_ai_assistant_config.voice_provider | string | null | TTS provider ID from the voices catalog (telnyx, aws, azure, elevenlabs, minimax, ...). Lowercase letters, numbers, _ and -. |
telnyx_ai_assistant_config.voice_provider_model | string | null | Provider voice model. |
telnyx_ai_assistant_config.voice_id | string | null | Provider voice ID. |
telnyx_ai_assistant_config.voice_name | string | null | Display name of the voice. |
telnyx_ai_assistant_config.voice_model | string | null | Full voice identifier, e.g. telnyx.Ultra.voice_abc123. |
telnyx_ai_assistant_config.voice_api_key | string | Write-only. Provider key for bring-your-own-key providers (elevenlabs, rime, resemble). It is stored as a secret and replaced by voice_api_key_ref; it is never saved on the assistant. |
telnyx_ai_assistant_config.voice_api_key_ref | string | null | Reference to the stored provider key. |
telnyx_ai_assistant_config.voice_speed | number | null | Speech speed multiplier. |
telnyx_ai_assistant_config.voice_language_boost | string | null | Language boost for supported voices (values in the voices catalog language_boost_values). |
telnyx_ai_assistant_config.voice_expressive_mode | boolean | null | Expressive mode for supported voices. |
telnyx_ai_assistant_config.voice_similarity_boost | number | null | ElevenLabs similarity boost. |
telnyx_ai_assistant_config.voice_style | number | null | ElevenLabs style. |
telnyx_ai_assistant_config.voice_use_speaker_boost | boolean | null | ElevenLabs speaker boost. |
telnyx_ai_assistant_config.background_audio | object | null | type (predefined_media, media_url or media_name) and value. |
telnyx_ai_assistant_config.transcription_model | string | null | Speech-to-text model, e.g. deepgram/nova-3. |
telnyx_ai_assistant_config.transcription_language | string | null | Language code or auto, from transcription languages. |
telnyx_ai_assistant_config.transcription_region | string | null | Transcription region. |
telnyx_ai_assistant_config.transcription_settings | object | null | Model tuning: eot_threshold (0.5-0.9), eot_timeout_ms (500-10000), eager_eot_threshold (0.3-0.9), keyterm (max 1000 chars), context (max 10000 chars). |
telnyx_ai_assistant_config.interruption_enable | boolean | null | Callers can interrupt the assistant. |
telnyx_ai_assistant_config.speaking_wait_seconds | number | null | Wait before speaking. |
telnyx_ai_assistant_config.speaking_on_punctuation_seconds | number | null | Wait after punctuation. |
telnyx_ai_assistant_config.speaking_on_no_punctuation_seconds | number | null | Wait when there is no punctuation. |
telnyx_ai_assistant_config.speaking_on_number_seconds | number | null | Wait after numbers. |
telnyx_ai_assistant_config.enabled_tools | string[] | null | Voice tools enabled on the agent. |
telnyx_ai_assistant_config.hangup_tool_description | string | null | When the assistant should hang up. |
telnyx_ai_assistant_config.dynamic_variables_enabled | boolean | null | Enable dynamic variables in the prompt. |
telnyx_ai_assistant_config.dynamic_variables_defaults | object | null | Default values of dynamic variables. |
telnyx_ai_assistant_config.dynamic_variables_automation_id | integer | null | Automation that resolves dynamic variables at call start. |
telnyx_ai_assistant_config.dynamic_variables_webhook_enabled | boolean | null | Resolve dynamic variables from your webhook. |
telnyx_ai_assistant_config.dynamic_variables_webhook_url | string | null | Your dynamic variables webhook URL. |
telnyx_ai_assistant_config.post_conversation_enabled | boolean | null | Run post-call analysis. |
telnyx_ai_assistant_config.post_conversation_instructions | string | null | Instructions for the post-call analysis. |
telnyx_ai_assistant_config.supports_unauthenticated_web_calls | boolean | null | Allow calls from the public web widget. |
telnyx_ai_assistant_config.widget_settings | object | null | Web widget appearance. |
telnyx_ai_assistant_config.data_retention | boolean | null | Provider data retention. |
telnyx_ai_assistant_config.transfer_from_number | string | null | Company number used as caller ID for external transfers. |
telnyx_ai_assistant_config.external_transfer_caller_id_mode | string | null | company_number or original_caller. |
Other keys in telnyx_ai_assistant_config (webhook_url, delivery_status_webhook_url, enabled_features, telnyx_tools, knowledge_*, elevenlabs_agent_id, imported_from, openai_realtime_sip_uri, debug_webhook_base_url) are maintained by the platform during sync; keep the values you read.
Background audio
json
| Type | Value |
|---|---|
predefined_media | A predefined sound, e.g. silence or office. |
media_url | A public audio URL. |
media_name | The name of an uploaded media file. |
Web widget
json
When the assistant has a telnyx_assistant_id, embed it on your site:
html
External call transfers
Voice assistants can transfer calls to external numbers or SIP URIs with external_handoff_targets (only allowed on voice assistants).
| Rule field | Type | Description |
|---|---|---|
id | string | Required. Unique per assistant. |
name | string | Required. |
label | string | Required. Unique per assistant. |
instructions | string | Required. When to transfer. |
destination_type | string | Required. external_number or sip_uri. |
phone_number | string | null | E.164 number for external_number. |
sip_uri | string | null | SIP URI for sip_uri. |
country_code | string | null | 2-letter country code. |
handoff_message | string | null | Spoken before transferring. |
timeout_secs | number | null | 5-120. |
enabled | boolean | null | Whether the target is active. |
Destinations must be unique. Set telnyx_ai_assistant_config.external_transfer_caller_id_mode and transfer_from_number to control the caller ID.
Refresh from the voice provider
To pull changes made directly at the voice provider, get the assistant with $syncFromTelnyx=true (see Get an AI assistant).
Report an issue with this documentation
Please log in to report issues with our documentation.