End-user setup guide
Audience: Salesforce administrator at the customer
Oversai reads Salesforce Cases — subject, status, origin, priority, owner and any custom fields on the Case — along with the email thread attached to each case, so they can be scored, coached on and reported against.
Who does this | Salesforce admin |
Time needed | About 10 minutes |
Access granted | Read-only |
Auth method | OAuth 2.0 — you sign in and approve Oversai |
Important: Unlike most integrations, you do not create a connected app. Oversai publishes one, and you approve it from your own Salesforce login. What decides how much data arrives is the Salesforce user account you sign in with — so the work below is mostly about preparing that user.
Before you start
A Salesforce account that can create permission sets and assign them — the System Administrator profile, or any profile with Manage Users and Manage Profiles and Permission Sets.
A decision about which Salesforce user Oversai will connect as. Use a dedicated integration user rather than a person's login — see Step 1.
An Oversai account with Admin access, to finish the connection at the end.
Production orgs only
The Connect button always sends you to login.salesforce.com. Sandbox and scratch orgs sign in at test.salesforce.com and cannot be connected through the standard flow — contact Oversai support if you need to pilot against a sandbox first.
⚠️ Be careful not to approve the wrong org: whichever org the browser is already signed in to is the one that gets connected.
Step 1 — Choose the user Oversai connects as
Setup > Users > Users
Oversai inherits exactly what this user can see.
A personal login works, but it breaks when that person leaves, changes password under a strict session policy, or is deactivated. Prefer a dedicated user named something like Oversai Integration.
If your org has Salesforce Integration user licences available, the Minimum Access – API Only Integrations profile is the intended starting point — it grants API Enabled and blocks UI login, and those two settings can't be edited away by accident.
Otherwise any profile works, so long as you add the permissions in Step 2.
Step 2 — Grant the permissions
Setup > Users > Permission Sets > New
Create a permission set such as Oversai Read Access, add the permissions below, then assign it to the user from Step 1.
Each row maps to something Oversai shows you — granting less simply means that part stays empty.
Permission | Where it lives | What it powers in Oversai |
|---|---|---|
API Enabled | System Permissions | Every call Oversai makes. Required — without it nothing syncs at all. |
Read on Case | Object Settings > Cases | The interaction list itself: subject, status, origin, priority, reason, type, and the link back to the case. Required. |
Read on Email Message | Object Settings > Email Messages | The email thread shown as the conversation transcript, and the input for AI scoring. |
Read on User (incl. the Email field) | Object Settings > Users | The agent's email on each case, which is how cases are matched to Oversai users and to their coaching records. |
Read on Case custom fields | Object Settings > Cases > Field Permissions | Your custom fields appear as filters and are stored on each interaction. |
View All on Case (or equivalent sharing) | Object Settings > Cases | Whether Oversai sees all your cases or only some — see the note below. |
⚠️ Record visibility is the setting that quietly halves your data
Oversai sees a case only if the user from Step 1 can see it. If your Case sharing model is Private or Public Read Only and that user owns nothing, Salesforce returns fewer rows — not an error — so the connection looks healthy while most cases never arrive.
Either tick View All on Case in the permission set, or put the user in a role high enough in the hierarchy to see the case queues you care about.
If counts look wrong later, check this first.
Field-level security matters as much as object access: a Case field the user cannot read is a field Oversai cannot read either.
Step 3 — Confirm connected apps aren't locked down
Setup > Security > API Access Control
Most orgs can skip this.
If your org has API Access Control switched on, every connected app is blocked until an admin allowlists it — approve the Oversai app there, and assign your Step 1 user access to it.
You will know this applies to you if Step 4 fails with this app is blocked by admin.
Step 4 — Connect in Oversai
Oversai > Data > Integrations > New Integration
1. Choose Connect to Salesforce
2. Give the integration a Name
This is the only field you type; there are no credentials to copy or paste.
3. Sign in to Salesforce
You are redirected to Salesforce.
Sign in as the user from Step 1, not as yourself, unless they're the same account.
4. Approve the permissions Salesforce lists on the consent screen
Consent screen shows | Why Oversai needs it |
|---|---|
Manage user data via APIs | Reading cases and their email threads |
Perform requests at any time | Staying connected without asking you to sign in again |
Access the identity URL service / basic information | Identifying which Salesforce org was connected |
5. You're connected
You are returned to Oversai and the integration is saved.
Oversai records which Salesforce instance you approved and uses it for every later call, so there is no environment or region to select.
What happens after you connect
The first cases appear within about five minutes, and Oversai re-checks every five minutes after that.
What syncs | Detail |
|---|---|
History on first sync | The last 15 days of cases. Older cases are not backfilled. |
Which records | Salesforce Cases only — open and closed. Leads, Opportunities, Tasks and Activities are not read. |
Case details | Subject, status, origin (shown as the channel), priority, reason, type, owner and owner email, created and last-modified time, and a deep link back to the case in Lightning. |
Custom fields | Every custom field on the Case object that your Step 1 user can read, available as a filter. |
Updates | A case that changes in Salesforce is re-read and updated in Oversai on a later sync. |
What Oversai can and cannot do
✅ Can read
Cases visible to the user you connected as, and their custom fields
Email messages attached to those cases
The name and email address of case owners
🚫 Cannot write
Create, edit, delete, close or reassign anything in Salesforce
Post case comments, send email, or trigger flows, workflows or Apex
Read Leads, Opportunities, Contacts, Accounts, Tasks, Chatter or Knowledge
See any record the connected user cannot already see
Oversai only ever issues read queries, so the connection is read-only in practice.
To make that guarantee structural, give the Step 1 user a profile with Read but not Edit on Case — the permission set in Step 2 asks for nothing more.
Revoke access
You can revoke access at any time:
Setup > Apps > Connected Apps OAuth Usage > Oversai > Revoke
Syncing stops at the next attempt, and data already in Oversai is unaffected.
If something isn't working
What you see | Most likely cause | Fix |
|---|---|---|
This app is blocked by admin during sign-in | API Access Control is on and Oversai isn't allowlisted. | Approve the app under |
Sign-in fails or the org looks wrong | You were signed in to a different org, or tried to connect a sandbox. | Sign out of Salesforce completely, then retry. Sandboxes aren't supported — contact support. |
Connection saves, no cases arrive | The connected user lacks API Enabled or Read on Case. | Confirm the permission set from Step 2 is actually assigned to that user, not just created. |
Far fewer cases than expected | Record visibility. The connected user can't see most cases. | Tick View All on Case, or raise the user's role. Compare against a Salesforce Cases list view run as that user. |
Cases arrive with no conversation text | The cases have no Email Message records, or Read on Email Message is missing. | Add Read on Email Message. If your team doesn't use Email-to-Case, there is no transcript to read. |
Agent names missing, coaching unassigned | Read on User, or field-level access to User.Email, is missing. | Grant Read on the User object including the Email field. |
Channel, priority or type filters are empty | These fill in from cases as they sync. | Wait for the first few syncs. If they stay empty after data has arrived, check field-level security on those Case fields. |
Syncing stopped after a Salesforce change | A field or permission the connected user relied on was removed, or the user was deactivated. | Confirm the user is active and still holds the permission set, then reconnect from Oversai. |
Everything pauses, then resumes | Your org hit its daily Salesforce API request limit. | Check |
If you experience any issues with the integration, please don’t hesitate to contact our support team at [email protected]. We’ll be happy to help you get everything up and running!