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

# Salesforce Integration

> Connect botBrains with your Salesforce Service Cloud

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.

<Note>
  **Private mode caps involvement at Private.** Private-mode replies are internal comments, never customer-visible, so these cases are classified as [Private involvement](/concepts/ticketing-performance#why-involvement-rate-not-resolution-rate)-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.
</Note>

## 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`:

```apex theme={null}
@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.

<img src="https://mintcdn.com/botbrains/iwe7EG2H5FvzvT9J/images/salesforce-integration/botbrains-integration-page.png?fit=max&auto=format&n=iwe7EG2H5FvzvT9J&q=85&s=6274db6731e12e42d9924bc354f192e0" alt="botBrains integrations page showing Salesforce integration form with fields for Salesforce URL, Consumer Key, and Consumer Secret, with a Connect button." data-generation-prompt="Navigate to platform.botbrains.io/~/integrations?integration=salesforce. Show the Salesforce integration configuration form with the Salesforce URL, Consumer Key, and Consumer Secret input fields visible. Include the Connect button. Use 1920x1080 viewport, collapse sidebar." width="1920" height="1080" data-path="images/salesforce-integration/botbrains-integration-page.png" />

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