> ## 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 Calls

> Place, read, end, and decline calls using a browser headset.

A browser call connects an active [agent session](https://docs.tracklysms.com/api-reference/voice/calls/browser-sessions.md) to a telephone recipient. Your authenticated backend calls these endpoints with the account's server-held API key. The key needs `voice_calls.write` for POST and `voice_calls.read` for GET, plus the **Voice Calls** entitlement. Authorize the signed-in user and the call in your application before forwarding requests.

Trackly must enable browser calling for the account before a new outbound call can be created. Without that enablement, `POST /browser-calls` returns `503 browser_voice_unavailable`; an exact same-key retry of an earlier call may remain available. The account also needs an assigned caller number and ordinary calling approval. A monitor session cannot place a customer call.

| Method | Path | Result |
| - | - | - |
| `POST` | `/api/v1/voice/browser-calls` | `202 {call}` and `Location: /api/v1/voice/browser-calls/{call.id}`. Acceptance does not prove ringing or answer. |
| `GET` | `/api/v1/voice/browser-calls/{callId}` | `200 {call}` with the latest stored and refreshed call state. |
| `POST` | `/api/v1/voice/browser-calls/{callId}/hangup` | `202 {call}` requesting call cleanup. For a monitor child, this ends only the listener. |
| `POST` | `/api/v1/voice/browser-calls/{callId}/decline` | `202 {call}` declining an incoming browser offer before answering; send an empty JSON object. |

## Place an outbound call

Use an active agent-purpose session and a stable `Idempotency-Key` for one attempt:

```http theme={null}
POST /api/v1/voice/browser-calls
Idempotency-Key: customer-call-123
Content-Type: application/json

{"sessionId":"665f1e2a9c4b1a0012ab34cd","from":"+14155550100","to":"+14155550123"}
```

`from` must be an assigned E.164 caller number; `to` must be an E.164 destination. Optional `maxDurationSeconds` must be within the account's configured limit. Optional `record` is a boolean; arrange required recording notices before requesting it. Optional `customData` accepts at most 32 entries, with nonempty string keys of at most 128 characters, string values of at most 1,024 characters, and a serialized JSON size of at most 8,192 bytes. Keys cannot start with `$` or contain a NUL character. Optional `recipientProvenance` follows the [Place a Call](https://docs.tracklysms.com/api-reference/voice/calls/place-call.md#body-parameters) contract. Reuse the same key and body after an uncertain response; a new key can place another call.

The returned `call.id` identifies the browser call. Read it with GET until `call.state` reaches the result you need; the response also identifies `sessionId`, the browser agent leg, and the telephone recipient leg when present. Incoming calls use the same GET and action paths. For hold, resume, and direct supervisor transfer, see [Browser call controls](https://docs.tracklysms.com/api-reference/voice/calls/browser-call-controls.md). For a separate receive-only supervisor, see [Browser listening](https://docs.tracklysms.com/api-reference/voice/calls/browser-monitor.md).

## Errors and ownership

The account and issuing API key must own the session and call. A missing or inaccessible resource returns `404 browser_resource_not_found`. A revoked or unsuitable session can return `409 browser_session_unavailable` or `409 monitor_session_read_only`; reusing a key with different call input returns `409 idempotency_conflict`. Invalid fields return `422`, and account or media concurrency limits can return `429`. A decline on a non-managed browser call returns `503 browser_voice_unavailable`. An accepted `202` can still precede a failed media attempt, so read the call state before retrying.


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