Create a voice agent

Create an agent from a full configuration. Supply agentId to choose the id yourself, or omit it and Tandem assigns one.

A supplied id that already names an agent is refused with 409 create_upsert_retired and nothing is written. This used to be an upsert; it cannot be one now, because a create writes the configuration to a version rather than to the agent itself, so repeating it over an existing agent would take that agent's configuration off the air and publish nothing in its place. Send configuration to that agent's version routes instead.

That also means a create interrupted partway through cannot be finished by repeating it: the agent exists, so the repeat is refused. Save a draft to it with PUT /v1/agent-media/agents/{agentId}/versions/{version}, or delete the agent and create it again.

The agent is created as a draft, not published. The configuration you send is written to version 0.1 and the agent has no publishedVersion, so it answers no calls until you publish that version with POST /v1/agent-media/agents/{agentId}/versions/{version}/publish. The response body is the agent's identity — it carries no configuration and no published pointer, both of which are absent by design. Read the configuration back from the version.

The agent is versioned from birth either way, so PUT /v1/agent-media/agents/{agentId} will not accept a configuration for it — every change goes to a draft and is published from there.

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agentId?string

Optional caller-chosen id. Must contain no # or control characters.

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 POST "https://example.com/v1/agent-media/agents" \  -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"}

Create a voice agent

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

409application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`