Starting a call — LiveGrid docs

start_call creates the room, dispatches an agent into it, and returns the token the human joins with. One round trip, because the three steps are useless apart.

The call#

{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "start_call",
    "arguments": {
      "room": "support-8f3a21",
      "user_identity": "daniel",
      "mode": "avatar",
      "avatar_id": "av_01H...",
      "caller_country": "SG"
    }
  }
}

Argument	Required	Notes
`room`	yes	Reusing a name joins that call rather than starting a second one
`user_identity`	yes	Who the human is, inside this room
`mode`	no	`voice` (default), `avatar`, `phone`. See modes
`avatar_id`	when `mode` is `avatar`	Which face. Per call, not per deployment
`agent_name`	no	Which worker fleet. Falls back to `AGENT_NAME`, then `livegrid`
`ttl_seconds`	no	Token lifetime, default 3600
`caller_country`	no	ISO 3166-1 alpha-2. Picks the nearest region. See Regions

What comes back#

{
  "token": "eyJhbGciOi...",
  "url": "wss://sg.example.com",
  "room": "support-8f3a21",
  "identity": "daniel",
  "expiresAt": "2026-09-10T12:04:11.000Z",
  "agent_name": "livegrid",
  "region": "sg",
  "mode": "avatar",
  "avatar_id": "av_01H...",
  "dispatched": true
}

url is the media server for the chosen region — hand it to the client SDK along with the token. It is not the control plane's own address, and confusing the two is the most common reason a token mints and the browser never connects.

Why the avatar is per call#

avatar_id travels as dispatch metadata rather than as worker environment. AVATAR_ID as an environment variable means one face per deployed fleet, so serving fourteen sales agents fourteen faces would mean running fourteen fleets.

The worker reads the metadata and falls back to its own environment, so a single-avatar deployment works with no metadata at all.

Ending one#

{ "name": "end_call", "arguments": { "room": "support-8f3a21" } }

Irreversible and immediate — everyone in the room is disconnected and the room is removed. There is no drain. Use it when the conversation is genuinely over, not to reclaim an idle room.

Adding somebody to a call already running#

start_call brings an agent with it, which is usually not what you want for a second participant. create_call_token mints a join token for an existing room and dispatches nothing:

{ "name": "create_call_token",
  "arguments": { "room": "support-8f3a21", "identity": "supervisor", "role": "observer" } }

observer hears everything and cannot be heard. That is the shape supervision wants, and it is a different thing from a muted human — a muted participant can unmute. See Access tokens and grants.