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, stableIdempotency-Key for each action:
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 return503 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:
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
EachIdempotency-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.
These controls require an existing managed browser call and compatible deployed API and media service. Source support alone does not establish customer acceptance.