Per-call configuration

Every request that starts a session takes the same fields for choosing what runs: test an unpublished draft, run an older version, change one setting for one call, or supply a definition stored nowhere. None of them changes what other callers hear.

Field	Does
`agent_id`	A stored agent; runs its published version unless `agent_version` says otherwise
`agent_version`	A published version number, or `"draft"` for the unpublished working copy. Needs `agent_id`
`agent_override`	Changes layered onto the named base
`agent`	A complete agent config, run for this session and stored nowhere
`agent_team`	Several agents for one session; `members[0]` answers

Accepted by POST /v1/calls/token (voice, video), POST /v1/calls/outbound (voice), POST /v1/calls/batches (voice) and POST /v1/chats (text). Send agent_id or agent, not both; agent_team excludes all four single-agent fields. These endpoints need the editor role. An inbound call or chat has no request: its agent can turn on the inbound webhook, whose answer may carry an agent_override.

agent_version: run the draft or an old version

Omit it to run what is published. "draft" runs the current working copy — validated and tool-pinned at request time and refused with the publish errors if it does not hold together. The draft is copied into the call at request time, so later edits do not affect it.

curl -X POST https://api.talqing.com/v1/calls/token \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    "agent_version": "draft",
    "contact_key": "qa-rehearsal"
  }'

const call = await talqing.calls.token({
  tokenRequest: {
    agent_id: "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    agent_version: "draft",
    contact_key: "qa-rehearsal",
  },
});

call = talqing.calls.token(
    agent_id="9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    agent_version="draft",
    contact_key="qa-rehearsal",
)

A "draft" outbound call rings a real phone and is billed like any other call.

agent_override: change fields for one call

AgentOverride is the AgentConfig field tree with every field optional — the same shape PATCH /v1/agents/{agent_id} takes. It merges by these rules:

In the override	Result
Key absent	Base value kept
Explicit `null` on a nullable field	Field cleared
Object	Deep-merged key by key
Object naming a different `provider`	Starts over from defaults (nested specs like `fallback` still merge)
List or scalar	Replaces the base value
`tools[]`, `on_enter`, `on_exit`, `on_user_turn_completed`, `mcps[]`, `faqs[]`, `handoffs[]` entries	Replaced whole — send complete objects

{
  "agent_id": "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
  "from_phone_number_id": "c2b7e5d1-08f4-4a63-b0de-71c4a9f6e332",
  "to": "+919876543210",
  "agent_override": {
    "tts": { "voice": "priya" },
    "greeting": {"message": "Hello Priya, this is Example Retail calling about order A-7X9."},
    "on_enter": null
  }
}

A hook or tool given as {"tool_id": "…"} attaches that tool at its currently published version, not the base’s pinned one.
channel can change only within what the endpoint runs: voice ↔ video on /calls/token; anything else is refused.
An override pins the base version it was merged against. A bare agent_id with no override follows whatever is published — which matters on a batch, re-read on every dispatch, and on an open chat, which follows the published agent between messages.

Declarations versus values

Field	Shape	Means
`agent_override.vars`	List of `{name, description, default, required}`	The agent’s declarations for this call; replaces the stored list
`vars` (top level)	`{name: string}`	The values for this session, over every agent’s defaults

The required-variable check runs on the merged config, so an override adding a default satisfies it. See variables.

agent: a whole definition for one call

Send a complete AgentConfig. Nothing is stored — no id, editor, version history or CoPilot. Inline tools, MCP servers and FAQs inside it live for that call only (on a stored agent they would be created as real ones).

curl -X POST https://api.talqing.com/v1/chats \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_key": "web-user-8842",
    "agent": {
      "name": "Trial evaluator",
      "channel": "text",
      "prompt": "You help someone evaluating our product during their trial. Do not invent pricing.",
      "llm": { "provider": "openai", "model": "gpt-5.6-luna" }
    }
  }'

Use it for definitions generated per request. For anything reused, store the agent and personalize with userdata or vars.

agent_team: several agents for one call

{"members": [...]}, 1–10 members, each described like a single agent (agent_id with optional agent_version/agent_override, or inline agent) plus a unique name. members[0] answers; others are reached by handoffs naming them. Details: agent teams on a call.

How the merged config is validated

Before anything is compiled or a provider called, in order:

The merged JSON must parse as an AgentConfig (422).
Team member names must be unique (422).
The resolved channel must match the endpoint.
Every required variable needs a value or default.
Inline code operations are compiled.
Full publish validation of every member — see validation.

Failures are a 400 with message: "the resolved agent config is invalid"; on a team each error is prefixed with the member’s name. Warnings come back as warnings on the response. On a batch the plan is stored with every call it places, so attach FAQs by faq_id rather than inline.

Reading back what ran

A call that ran the published agent unmodified stores no plan. Otherwise:

GET /v1/calls/{session_id} returns session.agent_version ("draft" for the draft, null for an inline agent), the tools, starting_prompt and greeting that ran, and the frozen agent_plan.
GET /v1/calls/batches/{batch_id} returns the campaign’s agent_plan.
The dashboard call list badges calls Inline, Draft, Overridden, Pinned or Team.

Versions

Publishing, rollback and tool pinning.

Agent teams on a call

Casts and roster handoffs.

Get started

Build

Guides

Per-call configuration

agent_version: run the draft or an old version

agent_override: change fields for one call

Declarations versus values

agent: a whole definition for one call

agent_team: several agents for one call

How the merged config is validated

Reading back what ran

Next

Versions

Agent teams on a call

​agent_version: run the draft or an old version

​agent_override: change fields for one call

​Declarations versus values

​agent: a whole definition for one call

​agent_team: several agents for one call

​How the merged config is validated

​Reading back what ran

​Next

Versions

Agent teams on a call

agent_version: run the draft or an old version

agent_override: change fields for one call

Declarations versus values

agent: a whole definition for one call

agent_team: several agents for one call

How the merged config is validated

Reading back what ran

Next