Skip to main content
Keep your Salesforce interface, contact selection, user login, and backend. Replace the calling integration in three places: 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.read and voice_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.
Download the browser SDK preview and retain it in your existing application’s approved script/static-resource setup. It includes SIP.js and license notices; no additional SIP.js installation is needed. Version and checksum metadata accompanies the bundle. If you serve several client businesses, your backend selects each client’s server-held Trackly key from the authenticated user’s authorized client mapping. Keep caller numbers, agents, sessions, and calls scoped to that client.

1. Add Trackly to your existing backend

The Trackly API base URL is:
Use 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:
Derive 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 exposes window.TracklyVoice.createVoiceBrowser. This example uses your existing backend adapter, audio element, selected devices, and status renderer. They are application dependencies, not new Trackly services:
Run 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:
Use your existing click lock while a handler is pending, and show rejected promises using their safe 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 their externalSubject. Create a WebRTC agent for that subject under the same key before issuing a monitor session.
The supervisor backend implements 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:
  1. Connect the headset, click your existing Call button, and verify the selected telephone receives the call.
  2. Check speech in both directions, mute, keypad, and hangup from each end.
  3. Place a second call after cleanup. Check that duplicate clicks do not place another call.
  4. Reload the component and test logout/recovery. Preserve any unknown attempt until your backend and Trackly resolve it; do not redial around it.
  5. 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.
  6. 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.
  7. 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.
Trackly’s media path has been tested outside Salesforce. Your existing component, org security settings, and office network still need this acceptance run. Keep your CRM activity logging and screen-pop logic connected to the returned Trackly call IDs. Add optional recording, queue, or supervisor controls using their Voice API contracts after confirming the features enabled for your account. For quota sizing, expiry, recovery, and optional Apex/LWC/Open CTI setup, use the configuration reference.