Update a voice agent

Replace an agent's configuration. Send the whole configuration, not a partial one: this is a replacement, so an optional field you omit is cleared, not carried over from the stored agent. Read the agent first and send it back with your changes applied if you only mean to change part of it. Creates the agent if the id doesn't exist yet.

That is how it behaves for an agent that predates versioning, and it is unchanged. An agent whose configuration lives on version rows no longer accepts a configuration here. The only keys such a body may carry are name and sourceTemplateId; any other key is rejected with 409 config_put_retired and nothing is saved, including the allowed keys that came with it. Save the configuration to a draft with PUT /v1/agent-media/agents/{agentId}/versions/{version} and publish it.

An agent is in the second state as soon as it has ANY version row — a published one or a saved draft. Every agent created since versioning shipped is there from the moment it exists: POST /v1/agent-media/agents and POST /v1/agent-media/agent-templates/{templateId}/instantiate both write the configuration they were given to a draft, so an agent created through either has never accepted a configuration here. An older agent crosses over when you save its first draft, or when Tandem migrates it onto versioning for you. Nothing crosses back.

So an integration that PUTs a whole configuration will start seeing 409 on an agent it used to be able to save. Do not branch on publishedVersion to predict it — a draft-only agent has no pointer and still refuses a configuration. Ask GET /v1/agent-media/agents/{agentId}/versions instead: an agent with any version listed takes its configuration through the version routes.

A rename is the one write that works in both states, but not with the same body. On a versioned agent {"name": "..."} alone is accepted and is the intended way to rename. On an unversioned one it is not: that path still validates the body as a whole configuration, so a name-only body is a 400 invalid_config for the fields it is missing. Either way the name itself is validated — empty or not a string is a 400. There is no agent-level description field to send in either state.

Authorization

bearerAuth

AuthorizationBearer <token>

A Tandem bearer token. Requests are scoped to the organization the token belongs to; no organization header is required.

In: header

Path Parameters

agentId*string

The agent's unique ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Internal label; callers never hear it.

Length1 <= length

systemPrompt*string

The agent's role, capabilities, and constraints. Rejected (create/update 400 invalid_config) when it exceeds 100,000 bytes once JSON-encoded — not the same as its raw character count, since escaping grows it.

Length1 <= length

greeting?string

Spoken verbatim as the agent's first turn.

interruptable?boolean

Whether caller speech interrupts the agent mid-sentence (barge-in).

Defaulttrue

channels?array<>

Which channels this agent answers on. Defaults to both, so a config that omits it behaves exactly as one written before the field existed.

It changes one rule: slots.tts is required only while voice is present. A chat-only agent saves and publishes with no voice, since the chat wire never carries one. A voice that IS set is validated on either channel — a voice that is there has to be a real one. An empty array is rejected.

Items1 <= items

Default

[  "voice",  "chat"]

slots*

greetingParts?array<>

Replaces greeting on calls. Each language must be a voice language of the agent. Templates render per part.

Itemsitems <= 10

variables?array<>

Agent-local values, referenced as {{agent.<name>}} wherever the configuration takes text. The organization-wide equivalent is {{org.<name>}}, managed separately. A reference to a name that does not exist is rejected at save time.

Itemsitems <= 50

Default[]

dispositions?array<>

Default[]

builtinTools?

The built-in call-control tools this agent may use. Every field defaults, so an agent saved without this block behaves exactly as before. No tool here requires a connected integration: the outside transfer is placed over the ordinary phone network, and everything else is internal to Tandem or local to the call.

dtmf?

Keypad input as ordinary caller input. A run of keypresses is grouped into one caller turn and delivered to the agent the way a spoken sentence is, with no tool call armed. Separate from builtinTools.captureDtmf, which is a tool the agent calls to ask a bounded question and block on the answer. Both may be on: while a captureDtmf collection is open the keypresses go into it instead, and digits already typed into an open group are carried into that collection rather than delivered twice.

thinkingCue?||

What the caller hears while a tool call runs. none is silence.

vad?

Turn-taking sensitivity. Every field is individually optional: whatever is absent falls back to the underlying voice pipeline's own default, and a partial block is a legal save.

turnDetection?

Which strategy decides the caller has finished speaking. vad tunes what counts as the caller starting to speak; this decides when they stop. Absent behaves exactly as mode: silence, which is what every agent has always used.

The Turn detection control on the Voice & Speech tab is being rolled out — if it isn't there, the rollout hasn't reached your organization yet. This API accepts the block either way, and the voice pipeline honors whatever is stored: the rollout gates the editor control, not the capability.

memory?

safety?

skills?

analysis?

Post-call analysis: a separate model pass over the finished transcript, extracting the built-in judgments and any fields you define.

Whether the transcript itself is kept is a separate setting, retention.transcripts, and analysis does not control it. With retention on — including by default, for an agent that has not set safety.redactPii — the transcript is stored whether or not analysis is enabled. With retention off, enabling analysis is the only thing that stores one.

retention?

What a finished call leaves behind. Independent of analysis: an organization can keep transcripts without paying for a model pass over them, and can analyze calls without this block set at all.

idle?

What happens when the caller goes silent mid-call.

limits?

Caller-visible bounds on the call itself.

reliability?

Failure-handling tuning. Each field falls back to a fixed default when absent, so an empty block is exactly today's behavior.

conversation?

How the agent's message history is kept inside the model's context window on a long call. An empty block behaves like strategy: slidingWindow with no other fields set — a 40-message window that drops the oldest messages first.

vocabulary?

Terms the agent must hear and say correctly on a call, such as product names. Voice only. Mishearings are replaced with the term in the caller's transcript, the voice says each term as its sayAs, terms with heardAs are listed in the agent's instructions, and a published agent's terms also tune speech recognition — see GET /v1/agent-media/agents/{agentId}/vocabulary-status.

dataCollection?

The fields this agent collects during a conversation. Setting it turns on the record_data tool (and, in chat, request_data_input). Live conversations use the published version, so publish after changing it. Omit to collect nothing. Read what was collected from GET /v1/agent-media/calls/{conversationId}/collected or GET /v1/agent-media/chat-conversations/{conversationId}/collected.

tools?array<||||>

Default[]

knowledge?

sourceTemplateId?string

The template this agent was created from, if any. Set once when the agent is created from a template and preserved across updates; read-only in practice. There is no link back — editing the template does not change this agent.

Response Body

`application/json`

curl -X PUT "https://example.com/v1/agent-media/agents/string" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "agent": {    "id": "string",    "name": "string",    "publishedVersion": "string",    "appearance": {      "hue": 0,      "colors": [        {          "hue": 0,          "saturation": 0,          "lightness": -0.2        }      ],      "scheme": "mono",      "shape": "circle",      "pattern": "glow",      "pupil": "dot",      "irisTexture": "fibers",      "ringCount": 2,      "ringWidth": 1.2,      "ticks": 12,      "dashLength": 2,      "dashGap": 1.5,      "rotation": 0,      "notches": true,      "lid": "round",      "texture": "none",      "temper": "calm"    },    "avatarImageUrl": "http://example.com",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "systemPrompt": "string",    "greeting": "string",    "interruptable": true,    "channels": [      "voice",      "chat"    ],    "slots": {      "llm": {        "model": "string",        "settings": {          "maxTokens": 1,          "temperature": 0,          "reasoning": {            "enabled": false,            "budgetTokens": 1024          }        }      },      "stt": {        "provider": "string",        "settings": {          "language": "string"        }      },      "tts": {        "voiceProvider": "string",        "settings": {          "language": "string",          "voiceId": "string",          "engine": "string",          "polly": {            "rate": "string",            "volume": "string"          },          "elevenlabs": {            "speed": 0.7,            "stability": 0,            "similarityBoost": 0,            "style": 0,            "useSpeakerBoost": true,            "textNormalization": "auto",            "pronunciationDictionaries": [              {                "id": "string",                "versionId": "string"              }            ]          }        }      },      "additionalVoices": [        {          "voiceProvider": "string",          "settings": {            "language": "string",            "voiceId": "string",            "engine": "string",            "polly": {              "rate": "string",              "volume": "string"            },            "elevenlabs": {              "speed": 0.7,              "stability": 0,              "similarityBoost": 0,              "style": 0,              "useSpeakerBoost": true,              "textNormalization": "auto",              "pronunciationDictionaries": [                {                  "id": "string",                  "versionId": "string"                }              ]            }          }        }      ]    },    "greetingParts": [      {        "language": "string",        "text": "string"      }    ],    "variables": [],    "dispositions": [],    "builtinTools": {      "transferToExternal": {        "enabled": false,        "destinations": []      },      "transferToVoiceAgent": {        "enabled": false,        "contextCarryover": "none",        "destinations": []      },      "captureDtmf": {        "enabled": false,        "maxDigits": 16,        "terminator": "#",        "timeoutMs": 10000,        "interDigitTimeoutMs": 3000,        "interruptsSpeech": true      },      "recordingControl": {        "enabled": false      },      "currentTime": {        "enabled": false,        "timezone": "America/New_York"      },      "setWorkflowVariable": {        "enabled": false,        "variables": []      }    },    "dtmf": {      "enabled": false,      "interDigitGapMs": 1500,      "terminator": "#",      "maxDigits": 32,      "interruptsSpeech": true    },    "thinkingCue": {      "kind": "none"    },    "vad": {      "silenceMs": 200,      "threshold": 0.7,      "startMs": 200,      "minVolume": 0.6,      "endOfTurnGraceMs": 600,      "bargeInMinWords": 1    },    "turnDetection": {      "mode": "silence",      "smartStopMs": 3000,      "preSpeechMs": 500,      "maxDurationSecs": 8    },    "memory": {      "depth": "none",      "customizeGreeting": false    },    "safety": {      "redactPii": true,      "steeringRules": [        "string"      ]    },    "skills": {      "builtins": [],      "custom": []    },    "analysis": {      "enabled": false,      "builtins": {        "sentiment": {          "enabled": false,          "prompt": "string"        },        "outcome": {          "enabled": false,          "prompt": "string"        },        "summary": {          "enabled": false,          "prompt": "string"        }      },      "fields": []    },    "retention": {      "transcripts": true    },    "idle": {      "enabled": false,      "timeoutMs": 10000,      "action": "reprompt",      "prompt": "string",      "maxReprompts": 2,      "onExhausted": "endCall",      "disposition": "string"    },    "limits": {      "maxCallDurationMs": 60000,      "warnBeforeEndMs": 5000,      "warnPrompt": "string"    },    "reliability": {      "maxConsecutiveTurnFailures": 1,      "toolTimeoutMs": 1000,      "steeringJudgeTimeoutMs": 500,      "handoffMaxHistoryMessages": 1,      "modelRetryMaxAttempts": 1,      "modelRetryInitialDelayMs": 100,      "modelRetryMaxDelayMs": 100    },    "conversation": {      "strategy": "slidingWindow",      "windowSize": 10,      "summaryRatio": 0.1,      "preserveRecentMessages": 2,      "pinFirst": 1,      "proactiveCompressionThreshold": 0.3    },    "vocabulary": {      "terms": []    },    "dataCollection": {      "fields": [        {          "key": "string",          "label": "string",          "kind": "full_name",          "required": false,          "prompt": ""        }      ]    },    "tools": [],    "knowledge": {      "kbId": "string",      "maxResults": 4,      "minScore": 0    },    "sourceTemplateId": "string"  }}

{  "error": "string",  "errors": [    {      "field": "string",      "message": "string"    }  ]}

{  "error": "string",  "message": "string",  "limit": 0,  "length": 0,  "reason": "string"}

{  "error": "string",  "message": "string",  "limit": 0,  "length": 0,  "reason": "string"}

{  "error": "string",  "message": "string",  "limit": 0,  "length": 0,  "reason": "string"}

{  "error": "string",  "message": "string",  "limit": 0,  "length": 0,  "reason": "string"}

Update a voice agent

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

404application/json

409application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`