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

# Hold, Resume, and Transfer a Browser Call

> Control an established managed browser call through your authenticated backend.

These controls act on a Trackly-managed browser call. Hold keeps the existing telephone and browser legs while separating their audio. Resume reconnects those same legs. Direct transfer dials a supervisor's telephone number and releases the salesperson's browser leg only after the supervisor answers and the new leg connects.

Call these routes from your authenticated backend using the account's server-held Voice API key with `voice_calls.write`. Authorize the salesperson and their call in your application before forwarding a request. Keep the API key out of the browser. The browser SDK exposes `hold`, `resume`, and `transfer` methods for an established call; connect their backend callbacks to the routes below.

For an outbound call, use the root browser call ID. For an inbound call, use the accepted browser agent child ID. The call must have an established salesperson audio leg. These controls do not operate on hosted telephone calls or a supervisor listener child.

## Hold and resume

Send an empty JSON object and a distinct, stable `Idempotency-Key` for each action:

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

{}
```

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

{}
```

Both return `202` with `{ "call": ..., "controlId": ..., "controlStatus": ... }`. The SDK methods are `voice.hold({idempotencyKey})` and `voice.resume({idempotencyKey})`; their backend callbacks are `holdCall(id, {idempotencyKey, signal})` and `resumeCall(id, {idempotencyKey, signal})`.

`controlId` identifies the exact native attempt derived from the `Idempotency-Key`. Its `controlStatus` is `pending`, `completed`, or `failed`, even if a newer attempt appears in `call.browserControl`. A matching `call.browserControl.id` on `GET /api/v1/voice/browser-calls/{callId}` or in SDK status can provide updates. If the latest ID differs, replay the same POST with its original key and body to get the exact `controlStatus`, including after the call ends. `completed` confirms the action; `failed` is a terminal rejection. A failed POST rejects `voice.hold()` or `voice.resume()` with `error.code` of `hold_failed` or `resume_failed`. A failure discovered later appears in `voice.status().code` and `onStatus` until the next control attempt. `holdState` is only the last confirmed media state (`held` or `connected`), so it can remain unchanged after a failed attempt. A `202` does not confirm that the media transition finished.

For the SDK helper, use `voice.status().localControl` to display the exact local hold or resume outcome: `{id, action, status}`. It is `null` before a local control, and `id` can be `null` until the POST response identifies the attempt. Status is `pending`, `completed`, `failed`, or `unknown`. The SDK updates it from matching GET status or same-key replay, so it remains accurate when `call.browserControl` describes a newer actor's control. If a call ends before the exact result can be recovered, the SDK releases media and reports `unknown` with `control_outcome_unknown`; a later explicit `voice.refreshStatus()` can recover the result. The local result remains visible after the call ends until another call starts. Starting a transfer clears the previous result.

## Direct transfer

Trackly currently has new transfer requests disabled. They return `503 browser_transfer_unavailable` until transfer is enabled for the serving API; an exact same-key replay can still recover an earlier attempt.

Send the supervisor's dedicated telephone number in E.164 format:

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

{"to":"+14155551234"}
```

This returns `202` with `{ "call": ..., "controlId": ..., "controlStatus": ... }`. The SDK method is `voice.transfer({to: supervisorE164}, {idempotencyKey})`; its backend callback is `transferCall(id, {to}, {idempotencyKey, signal})`. The top-level fields describe this exact transfer attempt. `GET` and SDK call status show the latest `call.transfer` with its `id`, `status`, and `to`; if its `id` differs, replay the same POST with the original key and destination to recover the exact attempt. A `202` may still report `pending`. An exact `controlStatus: "failed"` rejects the SDK method with `transfer_failed` and leaves its failed result in `localControl`. While transfer is pending, keep the original salesperson call in view; the salesperson is released only after the supervisor answers and the transfer connects. The transfer remains subject to the account's calling, billing, caller-number, destination, quiet-hours, and concurrency policies. A live conversation does not override those outbound checks; a supervisor transfer can be refused.

If the salesperson explicitly hangs up while transfer is pending, Trackly defers that hangup until the transfer settles. A successful handoff keeps the customer with the supervisor; a rejected or cancelled transfer ends the original customer call. The response can still show `transfer.status: "pending"` until media confirms the outcome.

If the call ends before the SDK can recover an exact transfer result, it releases local media and reports `busy: false`, `localControl: {id, action: "transfer", status: "unknown"}`, and `transfer_outcome_unknown`. A later explicit `voice.refreshStatus()` retries the original key and destination; the exact result updates `localControl` to `completed` or `failed`.

## Retries and errors

Each `Idempotency-Key` must be nonblank and at most 128 characters. After a timeout or uncertain control response, replay the same action, key, and JSON body to recover its `controlId` and `controlStatus`; the latest GET summary alone may belong to a different attempt. A key reused for a different action or destination returns `409 idempotency_conflict`. If the SDK reports `transfer_outcome_unknown` after the salesperson's headset disconnects, keep reading the same call until its transfer outcome settles; do not start a replacement transfer.

Invalid JSON or fields return `422`. A missing or inaccessible call returns `404`; a call without an eligible established browser agent leg returns `409`. Other policy, quota, or media errors use the response `code`. A `202` can precede a native control rejection; check the exact attempt's `controlStatus` before offering another hold or resume.

> [!NOTE]
>
> These controls require an existing managed browser call and compatible deployed API and media service. Source support alone does not establish customer acceptance.


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