API Referenceagents

Update Agent

Update an agent’s configuration.

Use this to change voice mode, system prompt, greeting, or voice. Switching voiceMode to “hosted” re-provisions the voice agent with built-in LLM.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

agent_idstringRequired

Headers

X-Sub-Account-IdstringOptional

Target a sub-account. Pass a sub-account ID to scope this request. Omit to use the master account.

Request

This endpoint expects an object.
namestring or nullOptional
descriptionstring or nullOptional
voiceModeenumOptional
enableMessagingboolean or nullOptional

When true, hosted-mode agents can send and read SMS/iMessage during calls.

modelTierenumOptional
systemPromptstring or nullOptional
beginMessagestring or nullOptional
voicestring or nullOptional
transferNumberstring or nullOptional
customToolslist of objects or nullOptional

Hosted-mode only. User-defined function tools the agent can call during a call. Replaces the full set on each update; send [] to clear all tools, or omit to leave unchanged. Ignored in webhook mode. Maximum 20 tools.

voicemailMessagestring or nullOptional
callScreeningIdentitystring or nullOptional
callScreeningPurposestring or nullOptional
sttModeenumOptional

Speech-to-text mode. ‘fast’ optimizes for latency, ‘accurate’ optimizes for transcription accuracy (~200ms additional latency).

ambientSoundenumOptional

Background ambience to mask synthetic silence between turns. ‘none’ disables; ‘office’, ‘coffee-shop’, ‘outdoor’ enable a quiet bed.

denoisingModeenumOptional

Audio denoising. ‘noise-cancellation’ (default) handles general noise. ‘noise-and-background-speech-cancellation’ is more aggressive for callers in cars, cafes, or near TVs ($0.005/min surcharge).

maxSilenceMsinteger or nullOptional10000-3600000

Hang up the call after this many milliseconds of caller silence. Default 600000 (10 min). Raise for IVR/hold-music workflows; lower to fail fast on dead lines. Range 10000 (10s) to 3600000 (1 hour).

voiceSpeeddouble or nullOptional0.5-2

Voice speed multiplier. 1.0 is normal pace; lower slows speech (0.5 is half speed), higher speeds it up (2.0 is double). Range 0.5 to 2.0.

interruptionSensitivitydouble or nullOptional0-1
How easily callers can interrupt the agent. 0 means the agent is never interrupted, 1 means the agent stops at the first sound. Default 0.8. Range 0.0 to 1.0.
enableBackchannelboolean or nullOptional

When true, the agent interjects short filler words like ‘uh-huh’ or ‘mhmm’ during longer caller utterances. Set false to keep the agent silent while the caller is speaking.

languageenumOptional

BCP-47 locale that drives the agent’s speech recognition and pronunciation. See the enum for the full set of supported codes.

Response

Successful Response
idstring
namestring
descriptionstring or null
voiceModeenum
voicestring
createdAtdatetime
enableMessagingbooleanDefaults to true
modelTierenumDefaults to balanced
systemPromptstring or null
beginMessagestring or null
transferNumberstring or null
customToolslist of objects or null
voicemailMessagestring or null
callScreeningIdentitystring or null
callScreeningPurposestring or null
sttModeenumDefaults to fast

Speech-to-text mode. ‘fast’ optimizes for latency, ‘accurate’ optimizes for transcription accuracy (~200ms additional latency).

ambientSoundenumDefaults to none

Background ambience to mask synthetic silence between turns. ‘none’ disables; ‘office’, ‘coffee-shop’, ‘outdoor’ enable a quiet bed.

denoisingModeenumDefaults to noise-cancellation

Audio denoising. ‘noise-cancellation’ (default) handles general noise. ‘noise-and-background-speech-cancellation’ is more aggressive for callers in cars, cafes, or near TVs ($0.005/min surcharge).

maxSilenceMsintegerDefaults to 600000

Hang up the call after this many milliseconds of caller silence. Range 10000 (10s) to 3600000 (1 hour). Default 600000 (10 min).

voiceSpeeddoubleDefaults to 1
Voice speed multiplier. Range 0.5 to 2.0. Default 1.0.
interruptionSensitivitydoubleDefaults to 0.8
How easily callers can interrupt the agent. Range 0.0 to 1.0. Default 0.8.
enableBackchannelbooleanDefaults to true

When true, the agent interjects short filler words like ‘uh-huh’ or ‘mhmm’ during longer caller utterances. Defaults to true.

languagestringDefaults to en-US

BCP-47 locale that drives the agent’s speech recognition and pronunciation. Defaults to ‘en-US’.

numberslist of objects or null

Errors

422
Unprocessable Entity Error