The salesperson clicks your existing Call button and speaks through their
headset. Trackly handles the browser media connection and telephone call. This
requires adapting your calling code; the SDK is not a Twilio-compatible drop-in.
For businesses authorized for optional recipient screening, the backend can check a selected US recipient ahead of the Call click. Normal Voice accounts do not need this lookup or a date or source-record reference sent to Trackly. If you use screening, your backend supplies the actual qualifying date for that separate request; an opaque source-record reference is optional and you retain the underlying evidence. The salesperson still uses the same button.
Browser calling requires activation for your Trackly account. Contact Trackly
with your signup email and business name to confirm activation and an assigned
test number. That first test does not require completing Calling setup, saving
a business profile or activating paid services.
A downloaded SDK or an API key alone does not enable live calls.
Before you start
Trackly supplies or confirms:- Your account and a server-held API key with
voice_calls.readandvoice_calls.write. - Your voice-enabled caller number, approved media origins, call/session limits, and an API quota sized for your active agents.
- The account’s calling activation and agreed test arrangement.
1. Add Trackly to your existing backend
The Trackly API base URL is:Authorization: Bearer <Trackly API key> and Content-Type: application/json
for server-side requests. Keep that key in your existing backend’s secret store.
The browser receives only temporary headset credentials.
Create one reusable browser agent per salesperson with
Create an Agent:
externalSubject from your authenticated server-side identity. Store and
reuse the returned agent mapping under the same issuing API key; omit number.
After an uncertain creation response or 409 agent_exists, use
List Agents to find the intended mapping.
Expose these operations through your existing authenticated backend. The SDK
calls your functions; those functions call Trackly:
Session and call creation require an
Idempotency-Key. Persist the attempt key
and original input before submission, enforce user ownership on every operation,
and return the parsed response envelope unchanged. A timeout must not trigger a
new call attempt. The callback reference
contains exact signatures, responses, and an adapter example. See Browser
Sessions and Browser
Calls for the endpoint behavior.
New agent sessions and outbound browser calls return 503 browser_voice_unavailable
until Trackly enables the account; an exact same-key retry may still recover a
previously accepted request.
When a recipient withdraws permission during a call or through another channel,
your backend should record a voice opt-out
with that client’s Trackly key and a reference to the source record. This is a
server-side compliance action, separate from the headset SDK callbacks.
2. Replace the browser audio integration
Load the downloaded script once in the same component that owns your current softphone. It exposeswindow.TracklyVoice.createVoiceBrowser.
This example uses your existing backend adapter, audio element, selected devices,
and status renderer. They are application dependencies, not new Trackly services:
enableHeadset() once on a fresh helper when the user enables your softphone.
It checks for earlier work and then connects the headset. If recovery is required,
show an explicit cleanup action using voice.disconnect() and wait for confirmed
cleanup before connecting. Keep this helper for later calls in the same component.
Use HTTPS, allow microphone access, and retain your existing playback control for
browser autoplay restrictions. Device selections are fixed for one helper
instance. If your existing Salesforce wrapper needs new script or media origins,
see the optional Salesforce configuration reference.
You can keep your current backend and Salesforce component type.
3. Connect your existing buttons
Your Call button supplies the selected owned caller number and contact number, both in E.164 format:error.code. Do not automatically retry call creation.
Disable new calls while
busy is true. startCall() resolving means the call was
admitted; display the conversation as connected when call.state is
connected. Local media: "active" alone is not proof that the telephone was
answered. The SDK already polls call status; do not add a second polling loop.
For hold, resume, and transfer,
authorize the action in your backend. The controls return before the media change
is necessarily complete. For hold and resume, return the backend response’s
top-level controlId and controlStatus unchanged. The SDK matches that ID to
voice.status().call.browserControl.id; if a newer attempt supersedes the latest
summary, it replays the same action, key, and input to recover the exact
controlStatus. Display voice.status().localControl.status for the helper’s
own hold or resume, even when call.browserControl belongs to another actor.
Wait for completed or failed. A failed POST rejects
voice.hold() or voice.resume() with error.code hold_failed or
resume_failed. A failure discovered later appears in voice.status().code
and onStatus until the next control attempt. Show that failure to the
salesperson.
holdState remains the last confirmed media state. Use
voice.status().call.transfer.status to follow a direct transfer.
With receiveIncoming: true, a connected, available headset can receive calls
to the account’s assigned number. Show your incoming-call controls when
media === "ringing" and call.direction === "inbound". The SDK verifies the
invitation against Trackly before displaying it. Answer connects the headset to
the original caller; it does not dial that caller again. Decline dismisses that
offer, allowing another eligible agent to receive it within the calling deadline.
Hang up ends an accepted conversation.
Incoming routing uses the account’s default Trackly-managed queue and its issuing key.
The managed queue returns numbers: [] and numberAssignmentsApplicable: false;
inbound selection uses number ownership and the default queue.
The first receiving session creates that queue if none exists. An existing queue
owned by another key requires Trackly to reconcile the routing; it is never
silently replaced. Use the same issuing key for your agents and incoming routing.
Connect the headset before the telephone call arrives. Incoming routing is
chosen when the call reaches Trackly; connecting afterward does not reclaim a
call already routed elsewhere.
Browser-only supervisor listening
Use a separate supervisor helper for browser listening. It listens to an active salesperson’s audio leg without dialing a supervisor telephone number. The Trackly key used by your backend must have been created by a current account owner. Your backend must authorize the authenticated supervisor and derive theirexternalSubject. Create a WebRTC agent for that subject under the same key
before issuing a monitor session.
createSession({monitorCallId, signal}) with
{externalSubject, purpose: "monitor", targetCallId: monitorCallId} and
createMonitorCall({sessionId, targetCallId}, {idempotencyKey, signal}) with the
route above. Keep session and monitor-attempt keys stable across uncertain
outcomes. Use the existing getCall, hangupCall, and endSession callbacks
for the listener’s own child call and session.
The listener helper requests no microphone, sends a receive-only audio answer,
and blocks customer calling, incoming calls, mute, keypad, and coaching.
listener.hangup() requests listener-only cleanup and revokes its monitor
session; the salesperson and recipient remain connected. Create a new monitor
session to listen again. The listener ends if the target salesperson or call ends.
Use the regular agent helper for any two-way customer conversation.
Browser listening needs a compatible deployed API, media service, and SDK bundle
for the account. Source support alone does not establish that those releases or
account activation are live.
Test in your existing Salesforce dialer
Start with one salesperson and a consenting test recipient:- Connect the headset, click your existing Call button, and verify the selected telephone receives the call.
- Check speech in both directions, mute, keypad, and hangup from each end.
- Place a second call after cleanup. Check that duplicate clicks do not place another call.
- Reload the component and test logout/recovery. Preserve any unknown attempt until your backend and Trackly resolve it; do not redial around it.
- Call the assigned Trackly number from the telephone. Check ringing, Answer, two-way audio, and hangup from each end. Repeat with Decline and with the caller hanging up before the salesperson answers.
- When browser listening is activated, join one established call from the separate supervisor helper. Confirm the supervisor hears both sides without microphone permission, cannot transmit or send DTMF, and disconnects when the salesperson hangs up. Confirm listener hangup leaves the customer call active.
- When browser call controls are activated, hold an established customer call, confirm the recipient no longer hears the salesperson, then resume and confirm two-way audio. Transfer to a consenting supervisor telephone and confirm the salesperson leaves only after the supervisor answers.