Connect Your Salesforce Dialer

Keep your Salesforce interface, contact selection, user login, and backend. Replace the calling integration in three places:

Existing integration	Trackly replacement
Backend issues a Twilio browser token	Backend creates a Trackly browser session for the authenticated salesperson.
Twilio browser SDK manages headset audio	Trackly browser SDK connects the headset to Trackly’s media service.
Call button and telephony controls	Bind the same buttons to Trackly’s SDK methods and backend callbacks.

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.

Browser calling requires activation for your Trackly account. Complete your account’s calling setup and confirm activation with Trackly before testing. 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 commercial terms.

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:

https://api.tracklysms.com/api/v1/voice

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:

POST /api/v1/voice/agents

{
  "name": "Salesforce agent <unique user label>",
  "type": "webrtc",
  "externalSubject": "sf:<authenticated-org-id>:<authenticated-user-id>"
}

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:

SDK callback	Your backend calls Trackly
`createSession`	`POST /browser-sessions` with the server-derived `externalSubject`.
`getCurrentSession`	`GET /browser-sessions?externalSubject=...` for the same user.
`createCall`	`POST /browser-calls` with `sessionId`, `from`, and `to`.
`getCall`	`GET /browser-calls/{id}`.
`hangupCall`	`POST /browser-calls/{id}/hangup` with JSON `{}`.
`endSession`	`DELETE /browser-sessions/{id}` with JSON `{}`.

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 for these six methods.

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:

const voice = window.TracklyVoice.createVoiceBrowser({
  backend: tracklyBackend,
  remoteAudio: existingAudioElement,
  audioDevices: {
    microphoneId: selectedMicrophoneId,
    speakerId: selectedSpeakerId,
  },
  onStatus: renderCallStatus,
});

async function enableHeadset() {
  await voice.recover();
  if (voice.status().connection === "recovery_required") return;
  await voice.connect();
}

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:

async function callContact(from, to) {
  const state = voice.status();
  if (state.connection !== "ready" || state.busy) return;
  await voice.startCall(
    { from, to },
    { idempotencyKey: crypto.randomUUID() },
  );
}

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.

Existing control	SDK action
Hang up	`await voice.hangup()`
Mute / unmute	`await voice.mute(true)` / `await voice.mute(false)`
Keypad	`await voice.sendDtmf("5")` — one digit per action
Refresh displayed state	`voice.status()`; `onStatus` supplies updates automatically
Renew an expired idle headset	`await voice.renew()`
Disconnect / logout	`await voice.disconnect()` and server-side session revocation

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.

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.

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.

API Reference

V2 API Reference

Agent Account Setup (v2)

Agent Number Registration (v2)

Pending Sends (v2)

Partner Accounts (v2)

Messages (v2)

Contacts (v2)

Lists (v2)

Number Requests (v2)

Business Verification (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Usage & Billing (v2)

Data Import (v2)

Links (v2)

Clicks (v2)

Webhooks (v2)

Phone Validation (v1)

Voice Calls (v1)

API Reference (v1 - Deprecated)

Connect Your Salesforce Dialer

Before you start

1. Add Trackly to your existing backend

2. Replace the browser audio integration

3. Connect your existing buttons

Test in your existing Salesforce dialer

​Before you start

​1. Add Trackly to your existing backend

​2. Replace the browser audio integration

​3. Connect your existing buttons

​Test in your existing Salesforce dialer

Before you start

1. Add Trackly to your existing backend

2. Replace the browser audio integration

3. Connect your existing buttons

Test in your existing Salesforce dialer