CTI Adapter
A CTI Adapter is the JavaScript software component that connects a telephony platform to Salesforce so agents can handle phone calls inside the console.
Definition
A CTI Adapter is the JavaScript software component that connects a telephony platform to Salesforce so agents can handle phone calls inside the console. It runs in the Open CTI iframe in the softphone panel. When a call rings, the adapter receives the event from the phone system and calls Open CTI methods like screenPop and saveLog to open the right record and log the call. When an agent clicks a phone number, the adapter receives that click and tells the phone system to dial out.
The adapter is the actual code that makes computer-telephony integration work. It is usually supplied by a telephony vendor, shipped as an AppExchange package, and registered through a Call Center definition file. Note an important caveat: Open CTI is in maintenance mode and is scheduled for retirement on February 28, 2028. It is already unavailable for newly created Agentforce Service orgs. Salesforce now points new contact centers to Service Cloud Voice instead.
How a CTI Adapter wires a phone system into Salesforce
The Open CTI iframe and the postMessage sandbox
The adapter does not run as free code on the Salesforce page. It loads inside an iframe in the softphone panel, and every message it sends to Salesforce travels through the browser Window.postMessage() API. Salesforce treats that boundary as a security wall. For each message the adapter sends, the target is restricted to Salesforce. For each message Salesforce receives, it checks the format and the sender origin before acting on it. This is why one vendor adapter cannot read the Salesforce DOM or reach into another vendor adapter. Everything passes through the published sforce.opencti interface. The model also explains the HTTPS guidance. Salesforce recommends serving the adapter over HTTPS in the reqAdapterUrl element so traffic between the telephony server and the browser is encrypted. In Salesforce Classic, admins also had to allowlist the adapter domain (including any non-standard port such as myserver:8500) in console settings. Lightning console apps do not need that allowlist step. The sandbox is the reason CTI adapters from completely different vendors can coexist in the same org without colliding.
Methods the adapter calls into Salesforce
The adapter does its work by calling Open CTI methods. The most common is screenPop, which opens or focuses a record when a call arrives, and its sibling searchAndScreenPop, which runs a search first and then pops the result. After a call ends the adapter calls saveLog to write or update a record such as a Task or a Voice Call. notifyInitializationComplete is the handshake the adapter fires once it has loaded and is ready to receive calls, so Salesforce knows the softphone is live. refreshView re-renders the current Lightning page after the adapter changes data behind it. There are many more: runApex to invoke an Apex method, getSoftphoneLayout to read the configured screen pop and call log rules, enableClickToDial and disableClickToDial to control phone-number links, onClickToDial to react when an agent clicks a number, and a family of setSoftphonePanel methods that resize, relabel, and show or hide the panel. The mapping from a phone event to one of these calls is exactly what the adapter implements. A good adapter keeps that mapping predictable so agents see the same behavior on every call.
Events the adapter receives from the phone system
The other half of the adapter listens to the telephony platform. It subscribes to the vendor event stream and reacts to call lifecycle events: ringing, answered, held, resumed, transferred, conferenced, and hung up. It also tracks agent state changes such as Available, On Call, Wrap-Up, and Offline. Each event can trigger a different Salesforce action through Open CTI. An inbound ring usually fires a screen pop. A hangup usually fires a saveLog and may surface a wrap-up screen. A click-to-dial in Salesforce flows the other direction: the adapter catches onClickToDial, then asks the phone system to place the outbound call. Because the adapter sits between two systems with their own timing, sequencing matters. If saveLog runs before the call record exists, the log can attach to the wrong record or fail quietly. Vendors handle this with their own buffering, which is one reason adapter behavior differs from product to product. Admins rarely change this logic; they configure routing and call rules in the telephony platform and let the adapter relay the results.
The Call Center definition file
An adapter is registered in Salesforce through a Call Center definition file, an XML document built from three element types: callCenter, section, and item. The file tells Salesforce where the adapter lives and how the softphone should behave. The required items include reqAdapterUrl (where the adapter or softphone is hosted), reqInternalName (a unique identifier up to 40 alphanumeric characters that must start with a letter), and reqDisplayName (the label shown in Setup). The reqSalesforceCompatibilityMode item decides which interface the adapter supports, with allowed values Classic, Lightning, or Classic_and_Lightning. If you leave it out, it defaults to Classic, which is a common reason a Lightning adapter appears to do nothing. Optional items cover softphone width and height, supported languages, and screen pop rules. You import the file once from Setup under Call Centers, then clone that record to create additional call centers for the same softphone. The file usually ships inside the vendor package and updates when the vendor releases a new build, so admins import or re-import it rather than hand-editing it in production.
Classic CTI Toolkit versus Open CTI for Lightning
There are two generations of adapter, and they are not interchangeable. Older adapters target Salesforce Classic and were built on the desktop CTI Toolkit, which required software installed on each agent machine. Open CTI replaced that with a browser-based JavaScript API, so nothing has to be installed on the desktop. Salesforce ships separate Open CTI APIs for Classic and for Lightning Experience, and you cannot swap one for the other in custom code because they behave differently. An adapter written for Classic does not work in a Lightning console, and a Lightning adapter does not run in Classic. Most established vendors shipped both versions during the long Classic-to-Lightning transition; newer entrants ship Lightning only. When you inherit an org, checking which generation the installed adapter targets is the fastest way to predict whether it will survive a move to Lightning. With Open CTI now in maintenance mode, no new methods are being added to either API, so feature gaps you find today are unlikely to be filled before the 2028 retirement.
Maintenance mode, the 2028 retirement, and Service Cloud Voice
Open CTI is no longer the strategic direction for Salesforce telephony. The platform has placed it in maintenance mode, which means no new features, and has set a hard retirement date of February 28, 2028, after which Open CTI implementations stop working. It is already unavailable for newly created Agentforce Service orgs, so a brand new Agentforce Service environment cannot stand up a classic third-party CTI adapter at all. Existing orgs can keep running their adapters until the retirement date. The recommended replacement is Service Cloud Voice. Voice is built into Salesforce rather than bolted on through an iframe, and it integrates natively with Omni-Channel and the supervisor Command Center, plus call transcription and Agentforce assist. Voice still uses Open CTI methods under the hood for some interactions, but the contact center experience is owned by Salesforce instead of stitched together by a vendor adapter. If you run a third-party CTI adapter today, the practical task is to build a migration plan to Voice or a Voice-partner model well before the February 2028 cutoff rather than waiting for it to be forced.
Register a vendor CTI adapter with a Call Center
Registering a vendor CTI adapter means importing its Call Center definition file and granting agents access. This assumes the vendor managed package is already installed. Treat this as legacy plumbing: for a new build, evaluate Service Cloud Voice before standing up a third-party adapter, because Open CTI retires on February 28, 2028.
- Install the vendor package
Install the telephony vendor managed package from AppExchange into a sandbox first. The package delivers the adapter code and usually a Call Center definition file you can import or clone.
- Import the Call Center definition file
In Setup, search Call Centers, then choose Import and select the vendor XML file. Confirm reqAdapterUrl uses HTTPS and that reqSalesforceCompatibilityMode is set to Lightning or Classic_and_Lightning for a Lightning console.
- Assign call center users
Open the imported call center, click Manage Call Center Users, and add the agents who should see the softphone. A user only loads the adapter if they are a member of a call center.
- Add the softphone to the app
In the Lightning app you use for service, add the Open CTI Softphone utility item so the panel appears in the utility bar. Without it, agents have no place for the adapter to render.
- Pilot and watch the console
Test with a small agent group on real call patterns. Keep the browser console open to catch adapter JavaScript errors that admins never see otherwise, and verify screen pop and call logging both fire.
The hosted location of the adapter or softphone. Use HTTPS so traffic between the telephony server and the browser is encrypted.
Set to Classic, Lightning, or Classic_and_Lightning. It defaults to Classic, which silently disables a Lightning adapter if left unset.
The unique call center identifier, up to 40 alphanumeric characters, starting with a letter, with no spaces and unique in the org.
Optional items that size the softphone panel so the vendor UI fits without scrollbars inside the utility bar.
- If reqSalesforceCompatibilityMode is missing it defaults to Classic, and a Lightning adapter will appear installed but do nothing.
- Users who are not assigned to the call center never load the adapter, so a working install can still show no softphone for some agents.
- Open CTI retires on February 28, 2028 and is already blocked for newly created Agentforce Service orgs, so new deployments should plan for Service Cloud Voice.
- In Salesforce Classic you must allowlist the adapter domain and any non-standard port in console settings; Lightning console apps do not need this.
Prefer this walkthrough as its own page? How to CTI Adapter in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on CTI Adapter.
Hands-on resources to go deeper on CTI Adapter.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What does a CTI Adapter do inside the Open CTI iframe of a Salesforce console?
Q2. Which Open CTI method does a CTI Adapter call to surface the right record on an inbound call?
Q3. How is a CTI Adapter registered so a Salesforce console knows where to load it?
Discussion
Loading discussion…