Skip to main content
The botBrains Salesforce integration enables AI-powered case handling in Service Cloud. botBrains acts as a dedicated Salesforce user, so cases can be assigned to AI exactly like they are assigned to human agents.

​
How botBrains Works in Salesforce

  • botBrains runs as a dedicated integration user in your Salesforce org.
  • When a case is assigned to that user, botBrains processes it.
  • botBrains can add internal comments, reply to customers, update case fields, and escalate to a human.

​
Integration Modes

ModeBehavior
Sync-onlySync data and knowledge context only. No case replies.
Private modeAdds internal/private comments (agent assist workflow).
Automated modeSends customer-facing replies directly.
Case field updates can be enabled independently of reply mode and are recommended when customer-facing replies are enabled. In all modes, the AI can escalate cases to a human.

​
Prerequisites

  • Salesforce org with API access enabled
  • Salesforce Service Cloud enabled
  • Admin access in Salesforce Setup
  • A botBrains project where you want to connect Salesforce

​
Salesforce Setup

​
1. Enable On-Demand Service and Email-to-Case

Activate Email-to-Case and configure a botBrains external email address (example: bb.salesforce.dev+xyz@gmail.com) with forwarding as needed.

​
2. Create the Threading Token Apex API

Create a new Apex class in Developer Console > Apex Class > New named ThreadingTokenApi: 
@RestResource(urlMapping='/threading-token')
global with sharing class ThreadingTokenApi {

  @HttpGet
  global static String getToken() {
    String caseId = RestContext.request.params.get('caseId');
    if (String.isBlank(caseId)) {
      RestContext.response.statusCode = 400;
      return 'Missing caseId';
    }
    return EmailMessages.getFormattedThreadingToken((Id)caseId);
  }
}

​
3. Create a botBrains Permission Set

Create a permission set in: https://{org_id}.my.salesforce-setup.com/lightning/setup/PermSets/home Grant the following permissions. System permissions:
PermissionReason
API EnabledAPI access
View All DataRequired for Change Data Capture updates (wakes up the botBrains agent)
Chatter Internal UserInternal case comments
Send EmailSend case-related emails
Object settings:
ObjectPermissionReason
CaseEdit, View All Fields, Edit Access to All FieldsWork on and update cases
ContactView All FieldsRead contact details
Also configure:
  • Apex Class Access: add ThreadingTokenApi
  • Organization-Wide Email Address Access: allow required sender addresses

​
4. Create the Integration User

Create a dedicated user (for example, name botBrains, unique email like botBrains-bot@company.com) and configure:
  • User License: Salesforce Integration
  • Profile: API-only minimum access profile (Minimum Access - API Only Integration(s))
Then assign:
  • Permission Set License Assignment: Salesforce API Integration
  • Permission Set: your botBrains Integration permission set

​
5. Create an External Client App

Create the app in: https://{org_id}.my.salesforce-setup.com/lightning/setup/ManageExternalClientApplication/create Recommended settings:
  • Name / API Name: botBrains
  • Contact Email: support@botbrains.io
  • OAuth Redirect URL: https://api.botbrains.io/v1/salesforce/oauth_redirect (required, not used)
OAuth scopes:
PermissionReason
Manage user data via APIs (api)API access
Perform requests at any time (refresh_token, offline_access)Long-lived integration access
Access content resources (content)Email attachment access
Enable client credentials:
  • Enable Client Credentials Flow: enabled
  • Run As: integration user email address
After saving, copy:
  • Consumer Key
  • Consumer Secret

​
6. Enable Change Data Capture

Open: https://{org_id}.my.salesforce-setup.com/lightning/setup/CdcObjectEnablement/home Enable CDC for:
  • Case
  • EmailMessage

​
Connect Salesforce in botBrains

Open your project integration page: http://platform.botbrains.io/{project_id}/integrations?integration=salesforce Use:
  • Salesforce URL: https://{org_id}.my.salesforce.com/
  • Consumer Key and Consumer Secret from the External Client App
Important: use the my.salesforce.com domain for the integration URL, not the my.salesforce-setup.com URL. If you use thread association, ensure ThreadingTokenApi is available and enabled in your integration permissions.

​
Domain and org_id Examples

Supported Salesforce domain examples:
  • https://company.my.salesforce.com/
  • https://orgfarm-random_string-dev-ed.develop.my.salesforce.com/
In both cases, org_id is the subdomain before .my.salesforce.com. For production rollout decisions (mode selection, field updates, escalation model), coordinate with your botBrains contact.