Salesforce setup

This guide connects Salesforce as Escalate's CRM source. Escalate uses OAuth (Connected App self-install — no Salesforce App Exchange review). Plan ~10 minutes including the first poll-cycle confirmation.

What you'll need

• Admin role: Salesforce System Administrator OR a custom profile with Manage Connected Apps + read access to the Opportunity object. Escalate's Connected App is self-install-scoped; you do NOT need IT-team approval or an internal security review for the install itself (the DPA covers the read-only posture).
• Org ID: found at Setup → Company Information → Salesforce Org ID. Looks like 00D5g000003JxXyZ. You won't need it for the install itself — it's relevant only if you ever email support.
• OAuth scopes Escalate requests (self-installable):
  • api — read access to Opportunity, Account, and User records.
  • refresh_token — keep the connection alive across token expiry without requiring you to re-authenticate.

Escalate never writes to your Salesforce org. Every read is scoped to deals matching your configured trigger stage; no deletes, no updates, no field writes. Ever.

Step-by-step

1. In Slack, run /escalate config crm. Pick Salesforce from the vendor picker; Escalate posts a one-time install URL good for 5 minutes. Click it.

2. Salesforce opens the standard OAuth consent screen showing both scopes. Review and click Allow. (If your org uses a sandbox or custom My Domain, the consent prompt is identical; the redirect targets the same callback URL.)

3. Salesforce redirects back to Escalate. You'll see a "Salesforce connected" confirmation page listing the workspace ID and a brief "What Escalate will do / will NOT do" trust panel. Close that tab.

4. Back in Slack, run /escalate config trigger. Pick the Opportunity stage that should trigger channel auto-creation (most teams pick Negotiation/Review or Proposal/Price Quote). Set the minimum amount if you want to filter for higher-ACV deals.

5. Confirm the first poll cycle. Escalate polls Salesforce every 5 minutes. To force an immediate check: run /escalate retrofit and pick last 7 days. The next deal that hits your trigger will auto-create a deal channel — usually within 30 seconds of the stage transition.

Troubleshooting

OAuth-callback errors map to the following fixes. The exact error messages match what Salesforce + Escalate's OAuth helper return.

"Connection to Salesforce failed during token exchange."

Cause: Salesforce rejected the OAuth code, usually because the Connected App's callback URL changed or the org has IP restrictions on the OAuth callback endpoint. Fix: Run /escalate config crm again to get a fresh install link. If it persists, the founder can check the exact Salesforce error code in Sentry; ping with the workspace name and approximate time.

"Saving the connection failed (database error)."

Cause: Escalate's database hit a transient error during the token persist. Almost always self-recovers. Fix: Wait 60 seconds and try again. If it persists past 2 attempts, ping the founder.

"This connection request has expired or already been used."

Cause: OAuth state tokens are single-use and expire after 15 minutes. You may have left the OAuth tab open too long. Fix: Run /escalate config crm again.

"Your workspace is not registered with Escalate."

Cause: You're trying to connect Salesforce before installing the Slack app (or the Slack install was rolled back). Fix: Install the Slack app first via the Slack setup guide, then re-run /escalate config crm.

Salesforce shows "user lacks api permission" on consent

Cause: Your Salesforce profile doesn't grant API access. This is a profile-level setting separate from Connected App approval. Fix: Ask your Salesforce admin to enable API Enabled on your user profile. The Connected App install will then succeed on retry.

Token rotation message: "We've re-authenticated your Salesforce

connection"

Cause: Escalate's auto-recovery path detected an expired refresh token and silently re-issued one via your latest OAuth click. This is not an error — you'll see this if you re-ran /escalate config crm while a previous connection was healthy. Nothing to do.

How to find your Salesforce org ID

The org ID is only relevant if you're emailing support; Escalate's slash commands never require you to type it.

• From Salesforce: Setup → Company Information → the Org ID field at the top.
• From a Salesforce URL: any URL containing /lightning/r/... — the org ID is the 15-char ID starting with 00D in your Salesforce login domain string.
• From the Escalate console: the connected org ID appears on the Coverage Report header next to your workspace name.