Teams on a call

agent_team defines several agents for one session on the request that starts it. members[0] answers; the others are reached through handoffs entries that name them. Use it when the cast is generated per request. If the same agents answer every call, store them with handoffs pointing at each other by agent_id and send one agent_id instead.

{
  "agent_team": {
    "members": [
      { "name": "Front desk", "agent_id": "3f9a1c72-58b4-4a1e-9f27-6d0c5b8e4a13" },
      { "name": "Renewals", "agent_id": "c8e07b16-4a25-4d90-b7e3-91f2a6d0c845", "agent_version": 4 }
    ]
  }
}

Where it is accepted

Endpoint	Channels
`POST /v1/calls/token` (web call)	voice, video
`POST /v1/calls/outbound`	voice
`POST /v1/chats`	text
`POST /v1/calls/batches`	voice

A member on a channel the endpoint does not run is a 400. An inbound phone call has no request to carry a team: the number’s assigned agent answers, and it can still hand off to stored agents by agent_id. See inbound calls. agent_team is mutually exclusive with top-level agent_id, agent, agent_version and agent_override.

Member fields

string

required

This member’s name for this call, overriding the stored agent’s. Handoff entries reference it and the transcript records it. Unique across the call (a duplicate is a 422).

uuid

A stored agent. Exactly one of agent_id and agent is required.

AgentConfig

A complete agent definition, run for this call and stored nowhere.

integer | "draft"

Which version of agent_id to run. Omit for the published one.

AgentOverride

Changes layered on the base: absent keys are kept, null clears, objects deep-merge, lists replace. See per-call configuration.

A team has 1 to 10 members.

How members reach each other

Every member is in the call’s roster under its name, including members[0], so a specialist can hand back to whoever answered. A handoffs entry resolves:

With agent_id: to that stored agent at its latest published version. The team is not consulted.
Without agent_id: by name in this call’s roster. A name the team does not define is refused at creation.

A stored agent whose entries are name-only publishes with a warning, which is expected for an agent built to run in teams. To give a stored agent different edges for one call, send agent_override.handoffs; it replaces the stored list.

What is checked before the call starts

Everything is resolved and validated at request time, so a bad team is a 400 naming the problem rather than a call that connects and fails:

Each member’s merged config must be publishable, including the cross-agent handoff rules against the roster.
A member naming a stored agent with no published version: publish 'Renewals' before calling it.
A required variable that any member declares with no value in the request’s vars and no default.

A member nothing hands off to is a warning in the response’s warnings, not a refusal:

nothing hands off to 'Renewals', so it will never take a turn on this call

Version pinning: a member is pinned to its version at request time. A handoffs target named by agent_id follows whatever is published at the moment of the handoff. A batch resolves its team once and every call runs that same cast; the resolved plan is stored per call, so attach FAQs there by faq_id rather than inline. userdata and vars are one bag each per session, shared by every member and by any handoff target outside the team. Each agent’s vars fall back to its own declared defaults.

Example

A web call whose front desk routes to a renewals agent, with the front desk’s edges supplied for this call only.

curl -X POST https://api.talqing.com/v1/calls/token \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_key": "user-8412",
    "userdata": { "name": "Priya", "plan": "Growth" },
    "agent_team": {
      "members": [
        {
          "name": "Front desk",
          "agent_id": "3f9a1c72-58b4-4a1e-9f27-6d0c5b8e4a13",
          "agent_override": {
            "handoffs": [
              {
                "name": "Renewals",
                "description": "renewing, upgrading or changing an existing plan",
                "context": "summary",
                "message": "Let me bring in the renewals desk."
              }
            ]
          }
        },
        {
          "name": "Renewals",
          "agent_id": "c8e07b16-4a25-4d90-b7e3-91f2a6d0c845",
          "agent_version": 4
        }
      ]
    }
  }'

const { server_url, participant_token, warnings } = await talqing.calls.token({
  tokenRequest: {
    contact_key: "user-8412",
    userdata: { name: "Priya", plan: "Growth" },
    agent_team: {
      members: [
        {
          name: "Front desk",
          agent_id: "3f9a1c72-58b4-4a1e-9f27-6d0c5b8e4a13",
          agent_override: {
            handoffs: [
              {
                name: "Renewals",
                description: "renewing, upgrading or changing an existing plan",
                context: "summary",
                message: "Let me bring in the renewals desk.",
              },
            ],
          },
        },
        {
          name: "Renewals",
          agent_id: "c8e07b16-4a25-4d90-b7e3-91f2a6d0c845",
          agent_version: 4,
        },
      ],
    },
  },
});

call = talqing.calls.token(
    contact_key="user-8412",
    userdata={"name": "Priya", "plan": "Growth"},
    agent_team={
        "members": [
            {
                "name": "Front desk",
                "agent_id": "3f9a1c72-58b4-4a1e-9f27-6d0c5b8e4a13",
                "agent_override": {
                    "handoffs": [
                        {
                            "name": "Renewals",
                            "description": "renewing, upgrading or changing an existing plan",
                            "context": "summary",
                            "message": "Let me bring in the renewals desk.",
                        }
                    ]
                },
            },
            {
                "name": "Renewals",
                "agent_id": "c8e07b16-4a25-4d90-b7e3-91f2a6d0c845",
                "agent_version": 4,
            },
        ]
    },
)

The browser joins with server_url and participant_token; see web calls. The same agent_team object works unchanged on the other three endpoints. Inline agents (agent) have no editor, version history or reuse, and disappear with the call. Prefer stored agents, use agent_override when one call differs, and keep inline definitions for agents generated per request.

Handoffs

The edges members reach each other through.

Per-call configuration

agent_version, agent_override and inline agent on a single-agent call.

Get started

Build

Guides

Teams on a call

Where it is accepted

Member fields

How members reach each other

What is checked before the call starts

Example

Next

Handoffs

Per-call configuration

​Where it is accepted

​Member fields

​How members reach each other

​What is checked before the call starts

​Example

​Next

Handoffs

Per-call configuration

Where it is accepted

Member fields

How members reach each other

What is checked before the call starts

Example

Next