CallCenter Metadata Type in SFDX & Open CTI

Architectural Overview#

The CallCenter metadata type is the foundation of Computer-Telephony Integration (CTI) in Salesforce Service Cloud and Sales Engagement. Whether your organization uses an Open CTI third-party softphone (such as Genesys Cloud, Five9, NICE CXone, or Cisco Webex) or a Partner Telephony contact center in Service Cloud Voice, CallCenter defines the adapter endpoint (adapterUrl), softphone utility bar dimensions, and vendor-specific configuration sections.

At runtime, Salesforce checks the logged-in agent’s User.CallCenterId lookup field. If populated, the Lightning Experience Softphone utility loads the reqAdapterUrl configured in that CallCenter metadata definition inside a secure iframe and initializes the Open CTI JavaScript SDK (sforce.opencti).

SFDX Directory & File Suffix#

Key Metadata Fields#

The CallCenter metadata type exposes the following XML fields:

Declarative XML & package.xml Examples#

SFDX Source File Example#

<?xml version="1.0" encoding="UTF-8"?>
<CallCenter xmlns="http://soap.sforce.com/2006/04/metadata">
    <adapterUrl>https://cti-adapter.acme.enterprise/softphone/index.html</adapterUrl>
    <customSettings>{&quot;reqSoftphoneHeight&quot;:&quot;550&quot;,&quot;reqUseApi&quot;:&quot;true&quot;,&quot;reqSoftphoneWidth&quot;:&quot;380&quot;,&quot;reqSalesforceCompatibilityMode&quot;:&quot;Lightning&quot;}</customSettings>
    <displayName>Global Open CTI Contact Center</displayName>
    <displayNameLabel>Display Name</displayNameLabel>
    <internalNameLabel>Internal Name</internalNameLabel>
    <sections>
        <items>
            <label>CTI Adapter URL</label>
            <name>reqAdapterUrl</name>
            <value>https://cti-adapter.acme.enterprise/softphone/index.html</value>
        </items>
        <items>
            <label>Use CTI API</label>
            <name>reqUseApi</name>
            <value>true</value>
        </items>
        <items>
            <label>Softphone Height</label>
            <name>reqSoftphoneHeight</name>
            <value>550</value>
        </items>
        <items>
            <label>Softphone Width</label>
            <name>reqSoftphoneWidth</name>
            <value>380</value>
        </items>
        <items>
            <label>Salesforce Compatibility Mode</label>
            <name>reqSalesforceCompatibilityMode</name>
            <value>Lightning</value>
        </items>
        <label>General Info</label>
        <name>reqGeneralInfo</name>
    </sections>
    <version>6.0</version>
</CallCenter>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Global_OpenCTI_Center</members>
        <name>CallCenter</name>
    </types>
    <version>68.0</version>
</Package>

Querying via SOQL & SFDX CLI#

You can query the CallCenter standard object in SOQL to inspect deployed call centers or audit how many agents are assigned to each call center:

SELECT Id, Name, InternalName, AdapterUrl, Version, CreatedDate
FROM CallCenter
ORDER BY Name ASC

Retrieve and deploy CallCenter metadata with the Salesforce CLI:

# Retrieve CallCenter metadata
sf project retrieve start --metadata CallCenter:Global_OpenCTI_Center

# Deploy CallCenter metadata
sf project deploy start --metadata CallCenter:Global_OpenCTI_Center

Senior Architect Best Practices & Gotchas#

• Keep customSettings and sections Synchronized: In CallCenter XML, both <customSettings> (escaped JSON) and <sections> hold softphone attributes like reqSoftphoneHeight and reqSalesforceCompatibilityMode. Always update both when modifying dimensions or URLs in source control.
• CSP and Framing Security: If adapterUrl points to an external domain, add that domain to CspTrustedSite and verify that the external telephony web server sends a Content-Security-Policy: frame-ancestors https://*.my.salesforce.com https://*.lightning.force.com header so browsers do not block the softphone iframe.
• User Assignment Automation: CallCenter metadata does not store the list of assigned users. Automate User.CallCenterId population in post-deployment scripts or user-provisioning Flow logic by querying CallCenter WHERE InternalName = 'Global_OpenCTI_Center'.

Frequently asked questions

What does the CallCenter metadata type configure?

It defines the computer-telephony integration (CTI) call center properties in Setup, including the Open CTI adapter URL, softphone height and width, and dialing options.

Where are CallCenter files located in SFDX source format?

They are stored in the force-app/main/default/callCenters/ directory with the .callCenter-meta.xml file extension.

Why does CallCenter XML use customSettings as a serialized string or sections?

CallCenter definitions originate from CTI XML import files where vendor-specific attributes are grouped into sections and items serialized inside customSettings.

Can I query CallCenter records using SOQL?

Yes, the CallCenter standard object is queryable in SOQL to inspect InternalName, Name, AdapterUrl, and Version, and to assign users via User.CallCenterId.