---
title: "The customer texted back. Salesforce never heard about it."
description: "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."
source: "https://noconaconsulting.com/blog/ringcentral-shared-sms-inbox-message-threads-api/"
---

# The customer texted back. Salesforce never heard about it.

_Build log · Doorvana · Garage door manufacturing & service_

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.

Nocona Consulting · November 18, 2026 · 9 min read

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](https://noconaconsulting.com/work/) calls, texts and voicemails reach Salesforce through [a server-side RingCentral sync](https://noconaconsulting.com/blog/ringcentral-open-cti-server-side-call-log-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 `AsyncApexJob` in 2,018 runs of the Queueable.
-   **A stopped schedule.** All 12 `CronTrigger` rows 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.

_A text to a user's direct number lands in that extension's message store, which the admin JWT can read. A text to a company number with the Business SMS shared inbox on lands only in a message thread, and only a user who is an SMS recipient on that number can read it._

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 Message Store API goes quiet, it does not fail

With the Business SMS shared inbox enabled on a company number, a sync built on `/extension/{id}/message-store` returns none of that number’s inbound texts and no error to say so. Outbound texts from that number and replies to it are in the Message Threads API. If your sync logs texts and someone texts from the main number, test with a reply to that number.

## The 403 that names the wrong cause

The threads endpoint answered:

```plaintext
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.

\[SMS\] permission is about the user, not the app

If `/account/~/message-threads` returns `403 InsufficientPermissions` with “application needs to have \[SMS\] permission” and the token’s scope already includes `SMS`, stop changing the app. Check whether the JWT’s user is an SMS recipient on the number whose threads you are reading.

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

```apex
/** 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

```apex
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:

```plaintext
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

```apex
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

```apex
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

```apex
// 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

```apex
@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.

Check the vendor's own log before you debug your sync

Every suspect on my list was inside Salesforce, and every one was innocent. The question that found the cause was whether the text existed in the place I was reading at all. When a record is missing and nothing failed, compare the vendor’s account-level log with the exact endpoint you call before you read your own code again.

## 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/messages` for the messages, `/account/~/message-threads/{id}` for the phone numbers (`ownerParty`, `guestParty`).
-   `403 InsufficientPermissions` with “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 exist` and 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.

-   RingCentral
-   Named Credentials
-   External Credentials
-   Queueable Apex
-   Platform Cache
-   Apex testing
-   Integration

Disclosure: Doorvana's owner is also a co-owner of Nocona Consulting. This is a real engagement between two separate companies, but not an arm's-length one — and not an independent reference. [More on the work page](https://noconaconsulting.com/work/).

## FAQ

### Why does the RingCentral Message Store API not return texts sent to the main company number?

When the Business SMS shared inbox is enabled for a company number or call queue, inbound texts to that number are not stored in any extension's message store. In this build, a 30-day search of every extension's message-store, including Deleted and Purged messages, found no trace of a text the admin portal showed as Delivered. Those messages are exposed through the Message Threads API instead: /account/~/message-threads and /account/~/message-threads/messages.

### Why does the RingCentral Message Threads API return 403 InsufficientPermissions "application needs to have [SMS] permission" when the app already has the SMS permission?

In this build the app had the SMS permission and the token's scope listed SMS, and the endpoint still answered 403 InsufficientPermissions with that message. The real gate was the user the JWT belongs to: only a user who is an SMS recipient on the shared number could read its threads. Authenticating as a user who was a recipient returned the messages with no change to the app.

### How do you store two RingCentral JWTs on one Salesforce External Credential?

Add a second authentication parameter to the same principal, for example SmsJwtToken beside JwtToken, and build the token request's merge field from the parameter name: {!$Credential.RingCentral.SmsJwtToken}. Each JWT user gets its own access token, so cache them under separate Platform Cache keys. If the parameter is missing, the callout throws System.CalloutException: Field RingCentral.SmsJwtToken does not exist, so catch it if the second sign-in is optional.

### Do RingCentral Message Threads API messages include the sender's and recipient's phone numbers?

Not on the message itself, in this build. A record from /message-threads/messages carried an id, threadId, direction, text and creationTime but no phone numbers. The numbers are on the thread: ownerParty.phoneNumber is the company's number and guestParty.phoneNumber is the customer's. Loading each thread once per sync run and reading the parties from it is what makes the message matchable to a Lead or Contact.

### How do you avoid duplicate records when two RingCentral APIs can return the same text message?

Give both passes the same external ID format and upsert on it. In this build, message-store rows and Message Threads rows both write RC\_Id\_\_c as sms: plus the message id, the two result sets are merged in a map keyed by that value before the DML, and the upsert on the unique external ID field keeps a text that both APIs return as one record.
