Salesforce Integration

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

Mode	Behavior
Sync-only	Sync data and knowledge context only. No case replies.
Private mode	Adds internal/private comments (agent assist workflow).
Automated mode	Sends 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.

Private mode caps involvement at Private. Private-mode replies are internal comments, never customer-visible, so these cases are classified as Private involvement-never Autonomous or Public, which both require a customer-facing AI reply. Enabling private mode lowers your Autonomous Rate by design, not because the AI performs worse. Involvement is recomputed on every reply, so it also stays provisional until a case closes.

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 the `botBrainsState` Case Field

Create a custom field on the Case object with the following settings:

Setting	Value
Field Label	`botBrainsState`
API Name	`botBrainsState__c`
Type	`Text`
Length	`255`
Default Value	`not-involved`

This field tracks botBrains involvement and can be used in automatic case assignment rules. Supported values:

escalated
active
not-involved

4. 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:

Permission	Reason
API Enabled	API access
View All Data	Required for Change Data Capture updates (wakes up the botBrains agent)
Chatter Internal User	Internal case comments
Send Email	Send case-related emails

Object settings:

Object	Permission	Reason
Case	Edit, View All Fields, Edit Access to All Fields	Work on and update cases
Contact	View All Fields	Read contact details

Also configure:

Apex Class Access: add ThreadingTokenApi
Organization-Wide Email Address Access: allow required sender addresses

5. 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

6. 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:

Permission	Reason
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

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

botBrains integrations page showing Salesforce integration form with fields for Salesforce URL, Consumer Key, and Consumer Secret, with a Connect button.

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.

Getting Started

botBrains Engineer

Train

Test

Deploy

Users

How botBrains Works in Salesforce

Integration Modes

Prerequisites

Salesforce Setup

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

2. Create the Threading Token Apex API

3. Create the `botBrainsState` Case Field

4. Create a botBrains Permission Set

5. Create the Integration User

6. Create an External Client App

7. Enable Change Data Capture

Connect Salesforce in botBrains

Domain and `org_id` Examples

​How botBrains Works in Salesforce

​Integration Modes

​Prerequisites

​Salesforce Setup

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

​2. Create the Threading Token Apex API

​3. Create the botBrainsState Case Field

​4. Create a botBrains Permission Set

​5. Create the Integration User

​6. Create an External Client App

​7. Enable Change Data Capture

​Connect Salesforce in botBrains

​Domain and org_id Examples

How botBrains Works in Salesforce

Integration Modes

Prerequisites

Salesforce Setup

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

2. Create the Threading Token Apex API

3. Create the `botBrainsState` Case Field

4. Create a botBrains Permission Set

5. Create the Integration User

6. Create an External Client App

7. Enable Change Data Capture

Connect Salesforce in botBrains

Domain and `org_id` Examples