---
title: "Connect a Web Call"
api: "POST /v1/api/calls/web/connect"
description: "Initiate a live web-based call session with an AI agent."
lastUpdated: "2026-11-04"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

Initiate a web call that runs entirely via WebRTC in the browser (no phone number required). The response carries the LiveKit URL and token your client uses to join the call.

Authenticate with your API key (`x-api-key`) or a dashboard session token, and call it from your server.

The workspace's wallet is checked first: a spent balance returns `400` with code `INSUFFICIENT_FUNDS`.

### Headers  

<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Request Body

<ParamField body="agentId" type="string" required>
  The ID of the agent that will handle this web call. The agent's call flow must be live.
</ParamField>

<ParamField body="mode" type="string">
  The mode of the call. Defaults to `voice`.
</ParamField>

<ParamField body="dynamic_variables" type="object">
  Values for `{{variable}}` placeholders in the call flow, as a flat object of strings.
</ParamField>

<ParamField body="initial_modality" type="string">
  The modality the session starts in.
</ParamField>

<ParamField body="pathwayId" type="string">
  A call flow ID. When that call flow has an active draft, the call tests the draft's settings instead of the published ones.
</ParamField>

<ParamField body="test_direction" type="string">
  `inbound` or `outbound`: which greeting to play. Defaults to the call flow's inbound greeting, or outbound for an outbound-only call flow.
</ParamField>

### Response Fields

<ResponseField name="status" type="string">
  `success`.
</ResponseField>

<ResponseField name="callId" type="string">
  A 10-character ID for this call.
</ResponseField>

<ResponseField name="callHistoryId" type="string | null">
  The Call History record for this call. Use it with [Get a Specific Call History](https://trillet-ai.jamdesk.app/v1/api-reference/endpoints/calls/call-history/get).
</ResponseField>

<ResponseField name="roomName" type="string">
  The LiveKit room, `web-<agentId>-<callId>`. Send it to [Disconnect a Web Call](https://trillet-ai.jamdesk.app/v1/api-reference/endpoints/calls/web/disconnect) to end the call.
</ResponseField>

<ResponseField name="token" type="string">
  The LiveKit access token for the room.
</ResponseField>

<ResponseField name="connection" type="object">
  `url` (the LiveKit server to connect to) and `token` (the same as `token` above).
</ResponseField>

<ResponseField name="agent" type="object">
  `id`, `name`, `model` (the agent's LLM settings) and `voice` (the agent's voice settings).
</ResponseField>

### Errors

| Status | Body | When |
| --- | --- | --- |
| `400` | `{"error": "x-workspace-id header is required"}` | No `x-workspace-id` |
| `400` | `{"code", "error", "message", "fix"}` | The agent has no live call flow. `code` says why, for example `FLOW_ARCHIVED` or `FLOW_INACTIVE` |
| `400` | `{"error": "Agent must have a phone number configured to use transfers"}` | The call flow has transfers but the agent has no number |
| `400` | `{"error": "Insufficient funds", "code": "INSUFFICIENT_FUNDS", ...}` | The wallet balance is spent |
| `401` | `{"error": "..."}` | Missing or invalid credentials |
| `404` | `{"error": "Agent not found or unauthorized"}` | No agent with that ID in this workspace |
| `500` | `{"error": "Failed to initiate web call", "details", "requestId"}` | Server error |

<ResponseExample>
```json
{
  "status": "success",
  "callId": "k3j9x0a1bq",
  "callHistoryId": "a2a2a2a2a2a2a2a2a2a2a2a2",
  "roomName": "web-a5a5a5a5a5a5a5a5a5a5a5a5-k3j9x0a1bq",
  "token": "<LIVEKIT_TOKEN>",
  "connection": {
    "url": "wss://livekit.example.com",
    "token": "<LIVEKIT_TOKEN>"
  },
  "agent": {
    "id": "a5a5a5a5a5a5a5a5a5a5a5a5",
    "name": "Front Desk",
    "model": { "provider": "openai", "model": "gpt-4.1-mini" },
    "voice": { "provider": "cartesia", "voiceId": "a0e99841-438c-4a64-b679-ae501e7d6091" }
  }
}
```
</ResponseExample>


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://trillet-ai.jamdesk.app/api-specs.zip
