Salesforce troubleshooting

Debug Salesforce connection, case creation, live messaging handoff, and agent reply sync issues.

Before debugging, have this ready:

• Admin access to both your Salesforce org and your OpenCX dashboard.
• A specific session ID (from Inbox) or Salesforce Case ID where the problem shows.
• The webhook URL shown in Settings → Integrations → Salesforce (for email issues).

Check connection status in Settings → Integrations → Salesforce as your first step. Most issues are credential or configuration related.

Email Cases

Jump to the symptom that matches what you’re seeing.

”OAuth credentials won’t save”

Likely cause: External Client App still activating, or credentials copied incorrectly.

Fix: wait 2–10 minutes after creating the External Client App, then retry. Re-copy the Consumer Key and Consumer Secret without leading or trailing spaces. Confirm the Login URL is https://login.salesforce.com (production) or https://test.salesforce.com (sandbox).

”Connect to Salesforce fails”

Likely cause: callback URL mismatch or popup blocked.

Fix: in Salesforce, open the External Client App and confirm the callback URL is exactly:

https://api.open.cx/backend/salesforce-case-management/oauth/callback

Allow popups for platform.open.cx in your browser.

”Handoff runs but no Case appears in Salesforce”

Likely cause: Apex trigger not deployed or inactive, Named Credential misconfigured.

Fix:

1. In Salesforce Setup → Apex Triggers, confirm CaseTrigger is active.
2. In Setup → Named Credentials, confirm OpenCX_Integration points to the webhook URL from OpenCX (re-copy if it looks stale).
3. In Setup → Apex Classes, confirm OpenSalesforceCaseManagement is saved and active.

”AI replies show as sent in OpenCX but the contact never receives the email”

Likely cause: outbound delivery trigger not deployed, or org-wide email deliverability blocked.

A plain EmailMessage insert in Salesforce creates a record in the Case Feed but does not actually transmit the email — transmission requires Messaging.sendEmail() via the OpenCxOutboundEmailSender trigger. If the trigger is missing, the AI reply logs to the Case Feed (showing Status Sent) but never leaves Salesforce.

Fix:

1. In Salesforce Setup → Apex Triggers, confirm OpenCxOutboundEmailSender exists, is Active, and targets EmailMessage. If missing, deploy it per Email Cases → Step 3, Trigger 5.
2. In Setup → Email → Deliverability, confirm Access level is All email (not System email only or No access).
3. Confirm the integration user’s profile has the Send Email permission.
4. Re-send the AI reply from OpenCX. It should now land in the contact’s inbox.

Run SELECT Id, CreatedDate, FromAddress, ToAddress, Status FROM EmailMessage WHERE ParentId = '<caseId>' AND Incoming = false ORDER BY CreatedDate DESC to confirm outbound records exist in Salesforce. If they do but the contact still doesn’t receive the email, enable a Debug Log for the integration user (Setup → Debug Logs → New with the integration user as Traced Entity), re-send the reply from OpenCX, then open the resulting log and look for the EmailMessage insert transaction — confirm OpenCxOutboundEmailSender executed and didn’t throw. If it didn’t run, double-check in Setup → Apex Triggers that the trigger is still Active.

”Customer replies open a duplicate Case instead of threading into the original”

Likely cause: OpenCxOutboundEmailSender is missing the call to EmailMessages.getFormattedThreadingToken(em.ParentId), or an older version of the trigger is deployed.

Fix: update OpenCxOutboundEmailSender to the version documented at Email Cases → Trigger 5. The current version appends the threading token to both the subject and the body, which is what Email-to-Case (Summer ‘22+) uses to attach customer replies to the same Case.

You can confirm by opening a recent outbound EmailMessage record on the Case Feed and checking its Subject/Body — you should see a ref:!...:ref token at the end. If the token isn’t there, the trigger is stale.

”Customer replies never reach Salesforce at all”

Likely cause: REPLY_TO_ADDRESS not set on the outbound trigger, or the reply-to address isn’t registered as a verified Routing Address.

Fix:

1. In OpenCxOutboundEmailSender, confirm REPLY_TO_ADDRESS is set to your customer-facing forwarding address (e.g. [e-mail]). Without setReplyTo(), replies go to the integration user’s personal Salesforce inbox and never reach Email-to-Case.
2. In Setup → Service → Email-to-Case → Routing Addresses, confirm that same address is listed and its status is Verified. Until verified, Salesforce drops forwarded mail silently.
3. Confirm the forwarding itself works: send a plain email to your forwarding address, then check Setup → Email Logs — if no delivery record appears within 30 minutes, the forward is failing before it reaches Salesforce (usually SPF / DMARC). Publish an SPF record on your domain that includes _spf.salesforce.com, or switch to an SRS-aware forwarder.

”Hit SINGLE_EMAIL_LIMIT_EXCEEDED in the Debug Log”

Likely cause: the org’s external email cap for the GMT day is exhausted.

Fix:

1. Wait for midnight GMT — the counter resets automatically, no code change required.
2. If you’re doing heavy iteration in a Developer / trial org (15/day cap), move testing to an Enterprise/Unlimited sandbox (5,000/day). The limit is a hardcoded edition characteristic — it cannot be raised on Dev Edition.
3. For high-volume production workloads that exceed 5,000/day, replace Messaging.sendEmail in OpenCxOutboundEmailSender with an HTTP callout to an external ESP (SendGrid / Postmark / Mailgun) via a Named Credential.

Note that setTargetObjectId(contactId) does not bypass this limit for external recipients — that optimisation only applies when the target is a Salesforce User record.

”Gmail forwarding stuck at Unverified”

Likely cause: Gmail’s forwarding handshake sent a verification code to Salesforce’s long @...case.salesforce.com address; Salesforce received it as a new Case but you didn’t retrieve the code to paste back into Gmail.

Fix:

1. In Gmail → Settings → Forwarding and POP/IMAP → click Re-send email next to the pending Salesforce address (sends a fresh code).

2. In Developer Console → Query Editor:

   SELECT Id, Subject, TextBody, CreatedDate
   FROM EmailMessage
   WHERE FromAddress = '[e-mail]'
   ORDER BY CreatedDate DESC
   LIMIT 1
   

3. Open the newest row and copy the 9-digit confirmation code from the TextBody.

4. Paste the code into Gmail’s verification input → Verify. Status should flip to Confirmed and forwarding is live.

The same pattern works for other mail providers (Outlook, FastMail, custom domains) — send a fresh verification, then pull the code from the newest EmailMessage in Salesforce.

”Rep replies don’t reach the contact”

Likely cause: webhook not firing or Named Credential URL outdated.

Fix: re-copy the webhook URL from Settings → Integrations → Salesforce and update the Named Credential. Confirm the Apex trigger fires on Case after insert.

Live Messaging

”MIAW settings won’t save”

Likely cause: Instance URL format wrong or PEM encoding incomplete.

Fix: include https:// in the Instance URL (e.g. https://yourcompany.my.salesforce.com). Ensure PEM keys include the -----BEGIN PUBLIC KEY----- and -----BEGIN PRIVATE KEY----- header and footer lines.

”Handoff fails with access token error”

Likely cause: key mismatch or wrong Auth Key ID.

Fix: regenerate the RSA key pair, re-register the public key in your Salesforce Embedded Service Deployment’s Auth Key settings, copy the new Auth Key ID, and update all six fields in the MIAW tab in OpenCX.

”Conversation created but no messages appear”

Likely cause: ES Developer Name mismatch or Omni-Channel not set up.

Fix: in Salesforce Setup → Embedded Service Deployments, copy the exact API Name (case-sensitive) and paste it into the ES Developer Name field in OpenCX. Confirm that Omni-Channel routing is configured for this deployment.

”Routing attributes missing in Salesforce”

Likely cause: Omni-Channel flow not reading the attributes.

Fix: in Salesforce Setup → Omni-Channel Flows, verify your flow references the attribute names (OpencxSessionId, Chat_Consumer_Type, Origin, Priority, Chat_language). Attributes are only useful if your flow reads them.

Still stuck?

If none of the above resolves the issue, open a support request with:

• The session ID from Inbox.
• The error message or unexpected behavior.
• Screenshots of your Salesforce setup (Named Credential, Apex Trigger status, or MIAW Embedded Service Deployment).

Limits & timing

	Value
External Client App activation	2–10 minutes after creation
Handoff retries	3 attempts with increasing delays
Transcript length	Up to 4,000 characters per handoff message
Private key display	Redacted after first save — re-enter to change

---

Related Documentation

Salesforce overview

Capabilities, supported channels, observability.

Email Cases

Re-verify OAuth, webhook, and Apex setup.

Live Messaging

Re-verify JWT credentials and routing attributes.

Handoff settings

Global handoff rules and office hours.