> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Sessions

> Create, recover, read, and end a browser headset session.

A browser session connects one authenticated headset user to Trackly's media service. Call these endpoints from your backend with a server-held Voice API key; never give that key or another user's session to the browser. The key needs `voice_calls.read` for GET and `voice_calls.write` for POST or DELETE, plus the **Voice Calls** entitlement. Derive `externalSubject` from the signed-in user and use a [WebRTC agent](https://docs.tracklysms.com/api-reference/voice/agents/create-agent.md) belonging to the same account and API key.

Trackly must enable browser calling for the account before a new agent session can be created. Without that enablement, `POST /browser-sessions` returns `503 browser_voice_unavailable`. An exact retry of an earlier session request may still return its retained result. A monitor-purpose session uses separate owner authorization and must target an established call.

| Method | Path | Result |
| - | - | - |
| `POST` | `/api/v1/voice/browser-sessions` | `201 {session, transport}` with temporary headset credentials. |
| `GET` | `/api/v1/voice/browser-sessions?externalSubject=...` | `200 {session, call}` for the current user; both fields are `null` when that user has a WebRTC agent but no owned session. This does not refresh credentials. |
| `GET` | `/api/v1/voice/browser-sessions/{sessionId}` | `200 {session}` with stored metadata, without transport credentials. |
| `DELETE` | `/api/v1/voice/browser-sessions/{sessionId}` | `200 {session}` after revocation; cleanup of its calls follows. |

## Create an agent session

Send the server-derived subject and a stable `Idempotency-Key`:

```http theme={null}
POST /api/v1/voice/browser-sessions
Idempotency-Key: headset-session-123
Content-Type: application/json

{"externalSubject":"sf:org-123:user-456","receiveIncoming":true}
```

For agent sessions, `receiveIncoming` is optional and defaults to `false`. Use `true` when the headset should receive calls to the account's assigned number. The response includes `session.id`, `agentId`, `externalSubject`, `status`, `expiresAt`, `backend`, and `receiveIncoming`, plus a `transport` object for the SDK. Keep transport credentials in the active browser session; GET responses do not return them. Reuse the same key and request body after an uncertain POST instead of creating another session.

For a listen-only supervisor, send exactly `{ "externalSubject": "...", "purpose": "monitor", "targetCallId": "..." }` with a stable key. Do not include `receiveIncoming`. The API key must belong to a current account owner, and the target must have an active browser salesperson leg. A monitor session cannot receive incoming calls. See [Browser listening](https://docs.tracklysms.com/api-reference/voice/calls/browser-monitor.md).

## Recover and end

Use the authenticated user's `externalSubject` with the current-session GET before connecting a headset after a page reload. It returns the owned session and active call metadata, but no new credential. Use the original same-key POST when the SDK needs to recover a still-valid session's transport. Revoke the session on logout with DELETE; a revoked session cannot admit another call.

The same account and issuing API key own session reads and revocation. A subject without an issuer-bound WebRTC agent returns `404 browser_agent_not_found` on current-session GET or session POST; create the agent first. A missing or inaccessible session ID returns `404 browser_resource_not_found`. Changed input under an existing key returns `409 idempotency_conflict`; an agent already owned by another session can return `409 browser_agent_busy`. Missing or invalid fields, including a missing or overlong idempotency key, return `422`. Session responses use `Cache-Control: no-store`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.