The customer texted back. Salesforce never heard about it.
A server-side RingCentral sync read every extension's message-store and still missed every reply to the main company number. With the Business SMS shared inbox on, those texts are only in the Message Threads API, which answers 403 InsufficientPermissions "application needs to have [SMS] permission" to any user who is not an SMS recipient on the number. The second JWT on the same External Credential, the thread lookup for phone numbers, and the upsert key that keeps both passes to one record.
A customer called back about a quote, and the call showed up on their Lead. The text they sent the next day did not. Everyone in the office could see it in the RingCentral app on their phone. The CRM never did.
Nothing errored. No job failed, no log line complained. The API the sync was reading had simply never been told about that text.
A sync with nothing wrong with it
At Doorvana calls, texts and voicemails reach Salesforce through
a server-side RingCentral sync:
RingCentralSyncQueueable runs every five minutes, pulls the account call log, and reads texts
from each User extension’s /extension/{id}/message-store into a custom Phone_Activity__c.
So the missing text had an obvious list of suspects, and I went down it:
- A failed run. No failed
AsyncApexJobin 2,018 runs of the Queueable. - A stopped schedule. All 12
CronTriggerrows were waiting, as they should be. - Filtering. No MMS filtering was dropping it.
- The watermark. The text pass reads from the newest stored
Start_Time__c, and that was current. - Conversation merging. Not in play.
Then I stopped trusting the sync’s own window and searched RingCentral directly: every
extension’s message store, 30 days back, including availability=Deleted and
availability=Purged. The text was not in any of them.
RingCentral’s own account-level messaging log, in the admin portal, showed it as Delivered, inbound to the main company number.
Where a text to the main number actually lives
The main number’s texts go to RingCentral’s Business SMS shared inbox. The number has
more than one SMS recipient. Inbound texts to it live in no
extension’s message store. On the recipients’ extensions the main number shows up with the
SmsSender and MmsSender features and never SmsReceiver.
RingCentral staff say as much on their community forum: the Message Store API “does not work if
the Shared Inbox feature is enabled for Company/CQ numbers”. Those texts are only exposed
through the Message Threads API: /account/~/message-threads and
/account/~/message-threads/messages.
Over the previous month people in the office had sent texts from the main number, and not one of the replies had reached Salesforce.
Two more things I would not have guessed. The main number belongs to a hidden extension of type
CompanyExtension with no extension number, and its message store returns 404. And
message-store?owner=Shared on a recipient’s extension does return call-queue texts, but never
the main number’s.
The 403 that names the wrong cause
The threads endpoint answered:
403 InsufficientPermissions
In order to call this API endpoint, application needs to have [SMS] permission
So I added the SMS app permission to the RingCentral app and issued a new token. The new
token’s scope listed SMS. The endpoint answered with the same 403 and the same sentence.
The real gate is the user the JWT belongs to. The Message Threads API only serves users who are SMS recipients on the number, and the admin user the sync signs in as is not one.
The obvious fix, making the admin user a recipient, was not free: once a number has more than one recipient, every recipient needs a Business SMS Booster licence, and the admin user would have needed one just to read. The other obvious fix, signing the whole sync in as a recipient, would have broken everything else, because the call log and other users’ mailboxes need the super admin.
Two JWTs on one principal
So the sync now signs in twice. The External Credential’s principal gets an optional second
parameter, SmsJwtToken, holding a JWT issued to a user who is already a recipient. The admin
JWT stays where it was.
force-app/main/default/classes/RingCentralClient.cls
/** Principal parameter holding the admin user's JWT: call log, every mailbox, recordings. */
public static final String ADMIN_JWT = 'JwtToken';
/**
* Optional principal parameter holding the JWT of a licensed company-number SMS recipient. The Message
* Threads API (Business SMS shared inbox) only serves SMS recipients; the admin user isn't one.
*/
public static final String SHARED_INBOX_JWT = 'SmsJwtToken';
public RingCentralClient(String jwtParameter) {
this.jwtParameter = jwtParameter == SHARED_INBOX_JWT ? SHARED_INBOX_JWT : ADMIN_JWT;
}
/** Each JWT user has its own token in the cache. */
private String cacheKey() {
return jwtParameter == ADMIN_JWT ? 'accessToken' : 'sharedInboxAccessToken';
} The token request builds its merge field from that parameter name:
force-app/main/default/classes/RingCentralClient.cls
request.setBody(
'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion={!$Credential.RingCentral.'
+ jwtParameter + '}'
); The separate Platform Cache key matters. The access token is cached in an org partition so the sync does not ask for a new one on every run. With one key, whichever client authenticated first would hand its token to the other, and the threads call would go out as the admin and get the 403 again.
The second sign-in is optional by design. The first live sandbox run had no SmsJwtToken on the
principal yet, and logged:
System.CalloutException: Field RingCentral.SmsJwtToken does not exist
The pass catches that, and a 403, and returns nothing, so calls and mailbox texts keep syncing:
force-app/main/default/classes/RingCentralSyncQueueable.cls
RingCentralClient client = new RingCentralClient(RingCentralClient.SHARED_INBOX_JWT);
try {
client.authenticate();
messages = client.getAllRecords(
'/restapi/v1.0/account/~/message-threads/messages?perPage=' + PER_PAGE
+ '&creationTimeFrom=' + EncodingUtil.urlEncode(isoTimestamp(dateFrom), 'UTF-8'),
MAX_PAGES
);
} catch (Exception noAccess) {
// No SmsJwtToken on the principal, a bad JWT, or a user who isn't an SMS recipient.
System.debug(LoggingLevel.WARN, 'Shared SMS inbox skipped: ' + noAccess.getMessage());
return activities;
} A thread message has no phone numbers
A record from /message-threads/messages carries an id, a threadId, a direction, the text and
a creationTime. It does not carry who sent it or who received it. Those are on the thread:
ownerParty is our number and guestParty is the customer.
So the pass loads each thread once per run, with one callout per thread, and stops loading when the transaction is within five callouts of its limit. A message whose thread was not loaded is skipped for that run:
force-app/main/default/classes/RingCentralSyncQueueable.cls
Map<String, Object> ownerParty = (Map<String, Object>) thread.get('ownerParty') ?? new Map<String, Object>();
Map<String, Object> guestParty = (Map<String, Object>) thread.get('guestParty') ?? new Map<String, Object>();
String ourNumber = (String) ownerParty.get('phoneNumber');
String customerNumber = (String) guestParty.get('phoneNumber');
String matchKey = PhoneActivityMatcher.normalize(customerNumber);
if (matchKey == null) {
return null;
} One smaller surprise on the way: the thread documentation shows list responses both as an object
with a records array and as a bare JSON array. RingCentralClient.getAllRecords now accepts
either, treating a bare array as a single page.
One text, two APIs, one record
The mailbox pass was widened at the same time. It used to read only User extensions; it now
reads call-queue (Department) mailboxes as well, whose texts had also been skipped. That
was the near miss. Reading the call-queue mailboxes was the whole plan before the shared inbox
turned up, and on its own it would have logged queue texts that the shared inbox also returns,
under different IDs.
Both passes therefore write the same external ID, sms: plus the message id, and the results
are merged before the DML:
force-app/main/default/classes/RingCentralSyncQueueable.cls
// Keyed by RC_Id__c: a text both passes return must be upserted once.
Map<String, Phone_Activity__c> texts = new Map<String, Phone_Activity__c>();
for (Phone_Activity__c text : pullTexts(client, textsFrom, extensionsById, userIdsByExtensionNumber)) {
texts.put(text.RC_Id__c, text);
}
for (Phone_Activity__c text : pullSharedInboxTexts(textsFrom, extensionsById, userIdsByExtensionNumber)) {
if (!texts.containsKey(text.RC_Id__c)) {
texts.put(text.RC_Id__c, text);
}
}
activities.addAll(texts.values()); A text that both APIs return is then one Phone_Activity__c, in the same run and across runs,
because RC_Id__c is the unique external ID the upsert keys on.
What the tests pin down
The Apex tests use an HttpCalloutMock that behaves like the real account: the threads
endpoints answer 403 unless the request carries the second JWT’s token.
force-app/main/default/classes/RingCentralSyncTest.cls
@IsTest
static void sharedInboxWithoutAccessIsSkipped() {
Test.setMock(HttpCalloutMock.class, new SharedInboxMock(403));
Test.startTest();
Integer created = new RingCentralSyncQueueable(null).sync();
Test.stopTest();
Assert.areEqual(3, created, 'calls and mailbox texts still sync when the shared inbox answers 403');
} The suite is 27 of 27 in the sandbox. It includes the reproduction (an inbound text to the main number that only the threads API returns becomes a matched Phone Activity on the Lead), a check that the threads calls carry the second JWT’s token, runs with a 403 and with no second JWT that still sync calls, a call-queue text, and the dedupe. A live sandbox run then picked up texts the old sync had been skipping.
As I write this the change is tested in the sandbox and has not yet gone to production.
Practical summary
- With the Business SMS shared inbox on, texts to a company number are in no extension’s message store. The Message Store API returns nothing for them and reports no error.
- Read them from the Message Threads API:
/account/~/message-threads/messagesfor the messages,/account/~/message-threads/{id}for the phone numbers (ownerParty,guestParty). 403 InsufficientPermissionswith “application needs to have [SMS] permission” can mean the JWT’s user is not an SMS recipient on the number, even when the app has the permission.- A second JWT fits on the same External Credential principal as another parameter. Give its access token a separate Platform Cache key.
- Make the second sign-in optional: catch
Field RingCentral.SmsJwtToken does not existand the 403, and let the rest of the sync run. - Use one external ID format across both APIs, merge by it before the DML, and upsert.