Agents
Update an agent
Change any setting on the agent’s working draft, or rename any version.
PATCH
Patch Agent
Send only what you want to change.
This preserves the saved Custom
A published version’s configuration is refused with
Send them alongside configuration to change and name a draft in one request.
Omit it and the change goes to your working draft — see below.
The error carries the labels, so you can choose without a second call. Then name it:
That form never guesses — use it whenever you know which draft you want.
Leave it out and your change applies to whatever the draft holds now — usually what you want for a
script changing one field.
On PATCH, omitted keys are unchanged; a
Sending
Switches take
Giving the transcriber, model or voice a backup provider? See Backups -
each one takes a slightly different shape.
Updating the greeting
To switch to an AI-generated opening with a five-second delay:message. To switch back, send
{"greeting":{"mode":"custom"}}; the saved message must be nonblank. To update the words too,
include message in that same block.
Omitted greeting fields keep their current values on PATCH. delay_ms: null resets the delay to
zero. There is no separate greeting prompt; update system_prompt to guide generated openings.
The delay must be an integer from 0 to 120000 milliseconds. See
Greeting fields
for mode requirements and what happens if the caller speaks first.
Choosing the version
?version=3 changes that version — the mirror of GET /v1/agents/{id}?version=3,
so reading and writing take the same selector.
409 version_immutable, whether you name it
by number or as live: it is frozen, which is what makes a rollback exact.
Renaming a version
label and notes go in the same body. They name the version the change lands on, and they are
not configuration, so they apply to any version - a published one included:
Where the change lands
On the agent’s working draft — and which one that is has to be unambiguous, because we will not guess on your behalf:
Nothing you change here reaches a caller until you publish that draft and
make it live.
Editing safely from two places
SendIf-Match with the document_revision you read, and a write composed against a stale copy is
refused with 409 version_document_stale rather than overwriting someone else’s change.
Channel instructions
system_prompt is the shared prompt. channel_prompts holds optional additions for
phone_inbound, phone_outbound, web_voice, web_chat, and whatsapp.
Only the matching addition is appended during a conversation. Each addition allows up to 65,536 characters.
null or blank value removes that channel’s addition.
channel_prompts: null clears all additions. An empty object changes nothing. Instructions are
versioned with the rest of the configuration and do not become live merely by saving.
Background sound
A soft looping sound played behind the agent on phone calls, like an office or a café. Two optional fields onconversation, read and written by create, update and get:
Sending
null for either field resets it to its default.
It plays only on phone calls: inbound, outbound, API and campaign calls. It never plays on a
web call. There is no per-call override, so POST /v1/calls uses
whatever the version answering the call is set to.
Uploaded sounds are chosen in the dashboard. A write accepts only
"none" and the ten ids
above, and the API has no endpoints to upload, list or delete sounds. An agent set to an
uploaded sound reads back with that sound’s id in background_sound. Sending that same id back
unchanged is accepted, so reading an agent and writing it straight back stays safe. Any other
value returns 400 document_invalid. See
Background Sound.Voicemail
What the agent does when a voicemail box answers an outbound call. Two optional fields oncall,
read and written by create, update and get:
null for either field resets it to its default. Inbound calls are never affected.
Whatever voicemail_action says, every outbound call is checked, and one a voicemail box answered
ends as voicemail with a voicemail object on the call. See
Voicemail.
Default Instructions
default_instructions is optional. Send only the rules you want to change: the rest stay as they
are, and leaving a rule out is never an error.
true or false. Pick-one rules take one of their values, or null to turn them
off. Rules that start with voice_ apply to calls, rules that start with chat_ apply to chats,
and the rest apply to both.Authorizations
Headers
Query Parameters
Body
application/json
Change any setting. Merge-patch: objects merge, lists replace whole, null clears.
Applies to the agent's newest draft. If the newest version is published, a draft is branched from the live version first — a published version's configuration cannot change.
Response
The version the change landed on, after it — the working draft, or the one ?version= named.
One agent at one version — the response of every agent read, create and update.
A request body is this same object minus the read-only fields, so what you send is what you read back.
Patch Agent