Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.botbrains.io/llms.txt

Use this file to discover all available pages before exploring further.

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

Create a custom field on the Case object with the following settings:
SettingValue
Field LabelbotBrainsState
API NamebotBrainsState__c
TypeText
Length255
Default Valuenot-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:
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

​
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:
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

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