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

PATCH
/ai-assistants/:id

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

FieldTypeDescription
acting_user_idinteger | nullUser whose identity the assistant uses for write actions during calls.
telnyx_ai_assistant_config.telnyx_assistant_idstring | nullRead-only in practice. ID of the synced voice agent at the provider.
telnyx_ai_assistant_config.sync_statusstring | nullpending, synced or error. Send pending when you change settings.
telnyx_ai_assistant_config.last_synced_atstring (date-time) | nullRead-only. Last successful sync.
telnyx_ai_assistant_config.error_messagestring | nullRead-only. Last sync error.
telnyx_ai_assistant_config.voice_runtimestring | nulltelnyx_builtin, custom_llm or openai_realtime_sip.
telnyx_ai_assistant_config.modelstring | nullLLM for the telnyx_builtin runtime, from voice LLM models.
telnyx_ai_assistant_config.use_custom_llmboolean | nullWhether the custom LLM runtime is used.
telnyx_ai_assistant_config.custom_llm_modelstring | nullModel used by the custom LLM runtime.
telnyx_ai_assistant_config.openai_realtime_modelstring | nullModel for the openai_realtime_sip runtime.
telnyx_ai_assistant_config.openai_realtime_voicestring | nullVoice for the openai_realtime_sip runtime.
telnyx_ai_assistant_config.greetingstring | nullFirst sentence spoken on the call.
telnyx_ai_assistant_config.descriptionstring | nullDescription sent to the voice provider.
telnyx_ai_assistant_config.voice_modestring | nullunified or distinct.
telnyx_ai_assistant_config.voice_providerstring | nullTTS provider ID from the voices catalog (telnyx, aws, azure, elevenlabs, minimax, ...). Lowercase letters, numbers, _ and -.
telnyx_ai_assistant_config.voice_provider_modelstring | nullProvider voice model.
telnyx_ai_assistant_config.voice_idstring | nullProvider voice ID.
telnyx_ai_assistant_config.voice_namestring | nullDisplay name of the voice.
telnyx_ai_assistant_config.voice_modelstring | nullFull voice identifier, e.g. telnyx.Ultra.voice_abc123.
telnyx_ai_assistant_config.voice_api_keystringWrite-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_refstring | nullReference to the stored provider key.
telnyx_ai_assistant_config.voice_speednumber | nullSpeech speed multiplier.
telnyx_ai_assistant_config.voice_language_booststring | nullLanguage boost for supported voices (values in the voices catalog language_boost_values).
telnyx_ai_assistant_config.voice_expressive_modeboolean | nullExpressive mode for supported voices.
telnyx_ai_assistant_config.voice_similarity_boostnumber | nullElevenLabs similarity boost.
telnyx_ai_assistant_config.voice_stylenumber | nullElevenLabs style.
telnyx_ai_assistant_config.voice_use_speaker_boostboolean | nullElevenLabs speaker boost.
telnyx_ai_assistant_config.background_audioobject | nulltype (predefined_media, media_url or media_name) and value.
telnyx_ai_assistant_config.transcription_modelstring | nullSpeech-to-text model, e.g. deepgram/nova-3.
telnyx_ai_assistant_config.transcription_languagestring | nullLanguage code or auto, from transcription languages.
telnyx_ai_assistant_config.transcription_regionstring | nullTranscription region.
telnyx_ai_assistant_config.transcription_settingsobject | nullModel 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_enableboolean | nullCallers can interrupt the assistant.
telnyx_ai_assistant_config.speaking_wait_secondsnumber | nullWait before speaking.
telnyx_ai_assistant_config.speaking_on_punctuation_secondsnumber | nullWait after punctuation.
telnyx_ai_assistant_config.speaking_on_no_punctuation_secondsnumber | nullWait when there is no punctuation.
telnyx_ai_assistant_config.speaking_on_number_secondsnumber | nullWait after numbers.
telnyx_ai_assistant_config.enabled_toolsstring[] | nullVoice tools enabled on the agent.
telnyx_ai_assistant_config.hangup_tool_descriptionstring | nullWhen the assistant should hang up.
telnyx_ai_assistant_config.dynamic_variables_enabledboolean | nullEnable dynamic variables in the prompt.
telnyx_ai_assistant_config.dynamic_variables_defaultsobject | nullDefault values of dynamic variables.
telnyx_ai_assistant_config.dynamic_variables_automation_idinteger | nullAutomation that resolves dynamic variables at call start.
telnyx_ai_assistant_config.dynamic_variables_webhook_enabledboolean | nullResolve dynamic variables from your webhook.
telnyx_ai_assistant_config.dynamic_variables_webhook_urlstring | nullYour dynamic variables webhook URL.
telnyx_ai_assistant_config.post_conversation_enabledboolean | nullRun post-call analysis.
telnyx_ai_assistant_config.post_conversation_instructionsstring | nullInstructions for the post-call analysis.
telnyx_ai_assistant_config.supports_unauthenticated_web_callsboolean | nullAllow calls from the public web widget.
telnyx_ai_assistant_config.widget_settingsobject | nullWeb widget appearance.
telnyx_ai_assistant_config.data_retentionboolean | nullProvider data retention.
telnyx_ai_assistant_config.transfer_from_numberstring | nullCompany number used as caller ID for external transfers.
telnyx_ai_assistant_config.external_transfer_caller_id_modestring | nullcompany_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
TypeValue
predefined_mediaA predefined sound, e.g. silence or office.
media_urlA public audio URL.
media_nameThe 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 fieldTypeDescription
idstringRequired. Unique per assistant.
namestringRequired.
labelstringRequired. Unique per assistant.
instructionsstringRequired. When to transfer.
destination_typestringRequired. external_number or sip_uri.
phone_numberstring | nullE.164 number for external_number.
sip_uristring | nullSIP URI for sip_uri.
country_codestring | null2-letter country code.
handoff_messagestring | nullSpoken before transferring.
timeout_secsnumber | null5-120.
enabledboolean | nullWhether 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.