The office phone rang all day. None of it reached Salesforce.
The RingCentral managed package is an Open CTI softphone. It logs calls handled in a signed-in user's browser tab, not calls that ring desk phones. Why it never saw the office line, the CTI Adapter URL that showed "This content is blocked" in a sandbox, and the server-side sync that replaced it: JWT auth through an External Credential, twelve scheduled jobs, upsert on an external ID, SOSL IN PHONE FIELDS matching, and the deploy lock a running schedule puts on its own code (corrected: Type.forName did not lift it).
The office phone rang all day, and none of it reached Salesforce.
The phone integration was installed. The admin settings said calls would be logged automatically. Someone called the main number from a cell phone as the first live test, the desk phone rang, the call was answered, and the softphone’s call history said “No calls yet”.
The integration everyone assumed would handle it only watches calls made from a browser. Nobody at this company makes calls from a browser.
What the managed package actually is
At Doorvana the plan was the obvious one: install RingCentral for Salesforce, the vendor’s managed package, and let it log every call to the office line on the right customer. That was my assumption going in.
The package is an Open CTI softphone. Its Setup Assistant creates a Call Center, the softphone lives in the utility bar, and its admin UI has settings that read like exactly what was wanted: “Auto create call log on: ringing” and “Auto create SMS log”. A test call placed from the softphone would have logged perfectly.
But that logging runs in the softphone, inside a signed-in user’s Salesforce tab. The office’s main number is routed by RingCentral to an extension that rings physical desk phones. Those calls never pass through a browser, so the package never sees them. And the client did not want the softphone at all: nobody here calls from Salesforce.
The sandbox detour: “This content is blocked”
Before that test could even run, the softphone panel in the sandbox showed:
This content is blocked. Contact the site owner to fix the issue.
The Call Center the Setup Assistant generated had its CTI Adapter URL pointed at a
production-style …--rcsfl.visualforce.com host. In a sandbox with enhanced domains, that
redirects to a My Domain that does not exist. Pointing the CTI Adapter URL at the
…--rcsfl.sandbox.vf.force.com host fixed it. Worth knowing, but it was fixing a component that
turned out not to be the answer.
Pulling the call log from the server instead
If the phones will not come to Salesforce, Salesforce goes to the phone system. RingCentral keeps an account-wide call log whatever device answered, so the replacement is a scheduled server-side sync:
- a RingCentral private REST app using the JWT auth flow, with Read Call Log, Read Accounts and Read Messages;
- an External Credential and Named Credential called
RingCentral, with the client ID, secret and JWT entered on the principal in Setup and never in source; - a Queueable that pulls
/restapi/v1.0/account/~/call-log?view=Detailedand each extension’smessage-storefor texts and voicemail, and upserts a customPhone_Activity__c; - a matcher that links each row to a Contact, open Lead or Account and logs a completed Task.
The secrets never appear in Apex. RingCentral issues its own JWT, so Salesforce’s built-in JWT Bearer protocol (which signs a JWT itself) does not fit; the External Credential uses a custom protocol and the token request merges the credentials in at callout time:
force-app/main/default/classes/RingCentralClient.cls
request.setEndpoint(NAMED_CREDENTIAL + '/restapi/oauth/token');
request.setHeader(
'Authorization',
'{!\'Basic \' & BASE64ENCODE(BLOB($Credential.RingCentral.ClientId & \':\' & $Credential.RingCentral.ClientSecret))}'
);
request.setBody(
'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion={!$Credential.RingCentral.JwtToken}'
); The Named Credential allows merge fields in the header and body, and does not generate its own
Authorization header:
force-app/main/default/namedCredentials/RingCentral.namedCredential-meta.xml
<allowMergeFieldsInBody>true</allowMergeFieldsInBody>
<allowMergeFieldsInHeader>true</allowMergeFieldsInHeader>
<generateAuthorizationHeader>false</generateAuthorizationHeader>
<namedCredentialType>SecuredEndpoint</namedCredentialType> Every five minutes is twelve jobs
A cron expression on a Schedulable fires at most hourly, so a five-minute cadence is twelve
scheduled jobs, one per five-minute mark, each enqueuing the sync:
force-app/main/default/classes/RingCentralSyncSchedule.cls
public static void scheduleEveryFiveMinutes() {
for (Integer minute = 0; minute < 60; minute += 5) {
String name = JOB_PREFIX + String.valueOf(minute).leftPad(2, '0');
System.schedule(name, '0 ' + minute + ' * * * ?', new RingCentralSyncSchedule());
}
} The Queueable checks AsyncApexJob and returns early if another sync is already processing,
so a slow run never overlaps the next one.
Re-reading on purpose, without duplicates
A call only reaches RingCentral’s call log once it ends, so a long call can start before the
newest one already stored. The sync therefore reads from the newest stored Start_Time__c
minus a two-hour overlap, and makes the overlap harmless with an upsert on an external ID:
force-app/main/default/objects/Phone_Activity__c/fields/RC_Id__c.field-meta.xml
<fullName>RC_Id__c</fullName>
<description>RingCentral call-log record id (call:...) or message id (sms:...). Upsert key, so a re-pulled call never duplicates.</description>
<externalId>true</externalId>
<type>Text</type>
<unique>true</unique> force-app/main/default/classes/RingCentralSyncQueueable.cls
Database.UpsertResult[] results = Database.upsert(
activities, Phone_Activity__c.RC_Id__c, false, AccessLevel.SYSTEM_MODE
); The same overlap is what picks up recordings and voicemail transcripts that arrive after the first pull. A field is only set when RingCentral sends it, so a later pull without the recording never blanks one already stored.
Matching a number to a customer
Phone numbers are stored however people typed them. The matcher normalizes every number to ten
digits and finds candidates with SOSL IN PHONE FIELDS, which ignores formatting:
force-app/main/default/classes/PhoneActivityMatcher.cls
String sosl = 'FIND {' + String.join(keys, ' OR ') + '} IN PHONE FIELDS RETURNING '
+ 'Contact(Id, AccountId, OwnerId, Phone, MobilePhone, HomePhone, OtherPhone, AssistantPhone ORDER BY LastModifiedDate DESC), '
+ 'Lead(Id, OwnerId, IsConverted, Phone, MobilePhone, Secondary_Phone__c WHERE IsConverted = false ORDER BY LastModifiedDate DESC), '
+ 'Account(Id, OwnerId, Phone ORDER BY LastModifiedDate DESC)'; When several records share a number, a Contact (an existing customer) wins over an open Lead,
which wins over an Account. A match logs a completed Task with TaskSubtype = 'Call',
CallType and CallDurationInSeconds, so it shows in the activity timeline like any logged
call. A missed call or voicemail from the last day also opens a call-back Task; older ones do
not, so a backfill of last week’s history cannot flood everyone’s task list. An outbound call
to a Lead stamps its Last_Outreach_Date__c.
A number nobody recognises becomes Unknown caller and lands in an Unknown Callers list view. Those are often the most important calls, a new customer ringing for the first time, so they are not left there. After-save triggers on Lead, Contact and Account re-run the match the moment a record gains that phone number, and link every earlier call from it. They use the trigger’s own records as candidates rather than SOSL, because the search index lags a record that was just saved.
The org refused the code, not the logic
Three deploy failures came from the platform rather than the sync.
The first:
This schedulable class has jobs pending or in progress
A scheduled class is locked while its jobs exist, and the lock covers every class it references. With twelve jobs always pending, any change to the sync meant stopping the schedule first. The fix I shipped was to give the scheduler no compile-time reference to the worker:
force-app/main/default/classes/RingCentralSyncSchedule.cls
public void execute(SchedulableContext context) {
// Resolved by name on purpose: a scheduled class locks every class it references at compile
// time, and deploys fail with "This schedulable class has jobs pending or in progress" while the
// jobs exist. With no static reference, the sync code can be redeployed under a running schedule.
Type syncType = Type.forName('RingCentralSyncQueueable');
if (syncType != null) {
System.enqueueJob((Queueable) syncType.newInstance());
}
} What actually works: stop the schedule before any deploy that touches the sync, and keep the sync’s classes out of deploys that do not need them.
The second: this project’s sourceApiVersion is 67.0, and at that version Apex database
operations in this org ran in user mode. The sync failed with:
Operation failed due to fields being inaccessible on Sobject Phone_Activity__c
The sync and matcher now say what they mean: WITH SYSTEM_MODE on queries, as system or
AccessLevel.SYSTEM_MODE on DML. Integration bookkeeping that must see every record with a
number should not depend on who happened to fire it.
The third: Salesforce automatically added the new Phone Activity related list to the Account mini layout, then rejected its own addition:
miniRelatedList: Phone_Activity__c.Account__c is not present in the full layout
The related list has to be on the full page layout before the mini layout can carry it.
And one in testing. Apex tests see the org’s real CronTrigger rows, so the test that schedules
the twelve jobs failed in the sandbox while the live sync was running:
The Apex job named "RingCentral Sync :00" is already scheduled for execution
Practical summary
- RingCentral for Salesforce is an Open CTI softphone. It logs what the softphone handles in a browser tab, not calls answered on desk phones.
- In a sandbox with enhanced domains, a CTI Adapter URL on a
visualforce.comhost can show “This content is blocked. Contact the site owner to fix the issue.” Use the sandbox’svf.force.comhost. - To log every call, pull the RingCentral call log server-side: JWT auth through an External
Credential, a Queueable for the callouts, twelve
Schedulablejobs for a five-minute cadence. - Each extension’s
message-storedoes not include texts to a company number that uses the Business SMS shared inbox. Those need the Message Threads API. - Re-read with an overlap and upsert on an external ID; late calls and late recordings then cost nothing.
- Match with SOSL
IN PHONE FIELDSon normalized numbers, and re-match from Lead, Contact and Account triggers when a number first appears. - A running schedule blocks deploys of the sync’s code, and
Type.forNamein theSchedulabledid not change that here. Stop the jobs, deploy, reschedule. - Say
WITH SYSTEM_MODEandas systemexplicitly in integration code; do not rely on the API version’s default.