CTI Adapter
A CTI Adapter in Salesforce is the JavaScript software component that runs in the Open CTI iframe inside a Salesforce console app and translates events between the agent phone system and Salesforce.
Definition
A CTI Adapter in Salesforce is the JavaScript software component that runs in the Open CTI iframe inside a Salesforce console app and translates events between the agent phone system and Salesforce. When a call rings in, the adapter receives the event from the telephony platform and calls Salesforce Open CTI methods like screenPop and saveLog to surface the right record and log the call. When the agent clicks a phone number in Salesforce, the adapter receives the click and tells the telephony platform to place the outbound call.
The adapter is the actual code that makes CTI work. It is supplied by the telephony vendor (Five9, Talkdesk, Genesys, RingCentral, Amazon Connect partner builds, and others), distributed as a managed AppExchange package, and registered in Salesforce through a Call Center definition file. Service Cloud Voice ships its own first-party adapter; third-party adapters all conform to the same Open CTI specification.
How a CTI Adapter works and what it does
The Open CTI iframe and the sandbox model
The CTI Adapter loads inside an iframe in the Salesforce console softphone panel. Salesforce sandboxes the iframe and routes communication through the sforce.opencti API. The adapter cannot directly read the Salesforce DOM; all interaction goes through the API. This isolation prevents one vendor adapter from interfering with Salesforce or another vendor adapter.
Methods the adapter calls into Salesforce
The most common Open CTI methods the adapter invokes are screenPop (open a record on inbound call), saveLog (write a call record after hangup), refreshView (re-render the Lightning page), notifyInitializationComplete (signal that the adapter is ready), and getEnclosingTabId (find which workspace tab the adapter is in for tab-aware actions).
Events the adapter receives from the phone system
The adapter listens for events from the underlying telephony platform: incoming call ringing, call answered, call hung up, call transferred, hold pressed, mute pressed, agent state changed (Available, Wrap-Up, Offline). Each event triggers different Salesforce actions through Open CTI. The mapping from phone event to Salesforce action is what the adapter implements.
Lightning vs Classic adapters
Older adapters target Salesforce Classic and use the deprecated CTI Toolkit JavaScript framework. Modern adapters target Lightning Experience and use Open CTI for Lightning. The two are not interoperable; an adapter built for Classic does not work in Lightning. Most vendors have shipped both; newer ones ship Lightning only.
Service Cloud Voice and the first-party adapter
Service Cloud Voice ships a Salesforce-built adapter that talks to Amazon Connect. It uses the same Open CTI API as third-party adapters but is tighter-integrated with the Voice Call object, transcription, and AI agent assist. For SCV deployments, the adapter is part of the package, not separately installed.
The Call Center definition file
Every adapter is registered in Salesforce through a Call Center definition file (XML). The file lists the adapter URL, softphone width and height, supported languages, and screen pop rules. Admins import the file from Setup, Call Centers, Import. The same file ships with the adapter package and updates with new vendor releases.
Custom CTI adapter development
Some orgs build their own adapter for in-house telephony platforms. The work is a JavaScript app that handles the phone vendor event stream and calls Open CTI methods. Salesforce ships sample code and a developer guide. Custom adapters are rare; most orgs go with a vendor package.
How to install and configure a CTI Adapter
The work is mostly importing the vendor package, registering the Call Center, and assigning users. The actual JavaScript code is the vendor problem.
- Install the vendor managed AppExchange package
Pick the right package for your edition (Lightning or Classic). Install in sandbox first.
- Import the Call Center definition file
Setup, Call Centers, Import. Upload the XML file the package shipped.
- Configure adapter settings
Edit the Call Center to set softphone dimensions, screen pop preferences, and any vendor-specific options (queue defaults, language).
- Assign users to the Call Center
Manage Call Center Users on the detail page. Add agents who should see the softphone.
- Verify in sandbox
Place a test inbound call. Confirm the adapter loads, the screen pop fires, the call logs to the right object.
- Promote to production
Repeat the install and assignment in production after sandbox testing.
- Classic CTI adapters (CTI Toolkit) are deprecated and do not work in Lightning.
- Open CTI methods are namespace-prefixed sforce.opencti for Lightning. Classic uses different names. Mixing patterns breaks the adapter.
- Sandbox refresh wipes Call Center user assignments. Re-assign after every refresh.
- Vendor package upgrades sometimes change the Call Center file; re-import on upgrade.
- Adapter latency contributes to screen pop SLA. Measure during pilot.
Trust & references
Cross-checked against the following references.
- Open CTI Developer GuideSalesforce Developers
- Set Up a Call CenterSalesforce Help
Straight from the source - Salesforce's reference material on CTI Adapter.
- Open CTI for LightningSalesforce Developers
- Service Cloud Voice OverviewSalesforce Help
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?
Q2. What API does a modern CTI Adapter use?
Q3. Who typically builds CTI Adapters?
Discussion
Loading discussion…