> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Salesforce Integration

> Connect BuildBetter with Salesforce to sync contacts, accounts, cases, and custom objects, and push meeting summaries

## What You Can Sync

**From Salesforce to BuildBetter:**

* Contacts → People
* Accounts → Companies
* Cases → Conversations (with all associated messages and emails)
* Custom Objects → Company-related records for filtering and reporting (subscriptions, licenses, contracts, etc.)

**From BuildBetter to Salesforce:**

* Meeting summaries → Event records on contacts and accounts

## Setup Instructions

### Prerequisites

* Active Salesforce account (Enterprise, Unlimited, or Professional edition)
* Salesforce API access enabled
* BuildBetter organization admin access

### Connection Steps

<Steps>
  <Step title="Navigate to Integrations">
    Go to **Settings → Integrations** in BuildBetter and find **Salesforce** in the CRM category.
  </Step>

  <Step title="Choose Environment">
    Before signing in, choose whether to connect to a **Production** or **Sandbox** Salesforce environment. BuildBetter routes OAuth to the correct endpoint, and your environment selection is preserved for token refresh.
  </Step>

  <Step title="Connect Your Account">
    Click **Connect** to start OAuth authorization, sign in to Salesforce, and approve the permissions BuildBetter needs to sync your data.
  </Step>

  <Step title="Configure Sync Settings">
    After connecting, choose which data to sync (see Configuration Options below).
  </Step>
</Steps>

<Note>
  **Sandbox Support:** Choose Production or Sandbox before connecting. The environment selection is sticky across token refreshes, so you won't need to reconfigure when tokens rotate.
</Note>

## Configuration Options

### Sync Contacts & Companies

**Toggle:** Sync Contacts & Companies

Enable this to sync Salesforce Contacts and Accounts to BuildBetter's People and Companies.

**Contact Fields to Sync:**
Choose which contact fields to sync. Default fields include:

* Id, FirstName, LastName (required)
* Email, Phone, MobilePhone
* Title, Department
* AccountId (for company linking)
* Mailing address fields
* CreatedDate, LastModifiedDate

**Additional contact fields you can sync:**

* LeadSource
* OtherPhone, Fax
* Full mailing address (Street, City, State, PostalCode, Country)
* Description and custom fields

**Account Fields to Sync:**
Choose which account fields to sync. Default fields include:

* Id, Name (required)
* Website, Phone
* Type, Industry
* NumberOfEmployees, AnnualRevenue
* Description
* CreatedDate, LastModifiedDate

**Additional account fields you can sync:**

* Billing address fields (Street, City, State, PostalCode, Country)
* ParentId (for account hierarchies)
* Custom fields specific to your Salesforce org

### Import Cases to Conversations

**Toggle:** Import Cases to Conversations

Enable this to pull Salesforce support cases into BuildBetter Conversations.

**What gets imported:**

* Case details (number, subject, description, status, priority, type)
* Case owner and contact information
* All case feed items (comments and posts)
* Email messages related to the case
* Live chat transcripts (if available in your Salesforce org)
* Messaging session data (if available in your Salesforce org)
* Full conversation history with proper attribution

**Feature Detection:**
BuildBetter automatically detects which conversation features are available in your Salesforce org and only syncs supported data types. Not all Salesforce editions have Live Chat or Messaging Sessions.

**Filter by Case Reason:**
You can limit Case imports to specific Case Reasons. After enabling Case import, select the Case Reasons you want to bring into BuildBetter — everything else is skipped. This is useful for narrowing imports to support, churn, or feedback-driven cases while keeping sales/internal cases out.

**Email-to-Case Matching:**
When importing Email Messages on Cases, BuildBetter now uses the actual sender email to attribute messages to the correct person, reducing incorrect thread attribution from forwarded or relay senders.

### Custom Object Sync

**Toggle:** Sync Custom Objects

Sync related Salesforce records — such as subscriptions, licenses, contract line items, or any custom object — into BuildBetter for richer filtering, reporting, and segmentation.

**How it works:**

* Pick the Salesforce custom object(s) you want to sync
* Map the relationship back to a Salesforce Account (so records land on the right BuildBetter company)
* Choose which fields to surface as company metadata in BuildBetter
* Records sync on the same schedule as the rest of the integration

**Use cases:**

* Filter signals and conversations by subscription tier
* Segment dashboards by license count or contract value
* Surface renewal dates and product entitlements next to customer feedback

<Tip>
  Custom Object Sync is especially useful for teams whose "true" account data — MRR, plan tier, seat count — lives in custom objects rather than the standard Account record.
</Tip>

### Recording Summaries to Contacts

**Toggle:** Recording Summaries to Contacts

Enable this to automatically push BuildBetter meeting summaries to Salesforce as Event records.

**What gets created in Salesforce:**

* Event record with meeting subject, start time, and end time
* AI-generated summary in the Description field
* Recording URL in the Location field
* Automatic association with meeting attendees (as WhoId)
* Automatic association with attendee accounts (as WhatId)

**Behavior:**

* Finds or creates Salesforce contacts for meeting attendees by email
* Links events to existing accounts when contacts have associated accounts
* Won't create duplicate events (checks by contact, start time, and call ID)
* Updates are idempotent - safe to run multiple times

## How It Works

### Sync Schedule

The Salesforce integration syncs automatically **every 4 hours** using an incremental sync strategy:

* **Incremental Sync:** Only fetches records modified since the last successful sync
* **Full Sync:** Can be manually triggered to sync all records
* **Lookback Window:** First sync or full sync defaults to last 5 days of data

### Sync Process

1. **Accounts First:** Salesforce accounts are synced first to establish company relationships
2. **Contacts Second:** Contacts are synced and linked to their associated accounts
3. **Cases Last:** Cases are synced with all conversation threads and participant data

### Data Matching

**Contacts:**

* Primary matching by email address
* Creates new person in BuildBetter if not found
* Email and phone matching enabled by default
* Links to company via Salesforce AccountId

**Accounts:**

* Matched by website domain or company name
* Linked to contacts via Salesforce's AccountId relationship
* Additional account metadata stored as custom fields

**Cases:**

* Unique by Salesforce Case ID
* Fetches all conversation sources (feed items, emails, live chat, messaging)
* Automatically detects which features are available in your org
* Creates full conversation thread with proper message ordering

### Meeting Summary Push

When a recording is completed in BuildBetter:

1. Job queued to push summary to Salesforce
2. For each meeting attendee:
   * Find or create Salesforce contact by email
   * Get associated account if contact has one
3. Create Event record with summary
4. Associate Event with contact (WhoId) and account (WhatId)
5. Include recording URL in Location field

## Troubleshooting

### Connection Issues

**"Salesforce authentication failed" / "Needs reauthorization"**

* Expired or invalid Salesforce connections are now clearly marked as needing reauthorization in the integration list. Click **Reconnect** to refresh the OAuth grant.
* Make sure you're connecting to the right environment — Production vs. Sandbox is selected before sign-in and preserved across token refreshes.
* Verify you have API access enabled in Salesforce and that your edition supports API access.

**Sync shows "error" status**

* Check the error message in Settings → Integrations
* Verify you haven't exceeded Salesforce API limits
* Try reconnecting the integration

### Data Not Syncing

**Contacts not appearing in BuildBetter**

* Make sure "Sync Contacts & Companies" is enabled
* Verify contacts have email addresses (recommended for matching)
* Check that contacts were recently modified (within the sync window)
* Wait for the next sync (every 4 hours) or trigger a manual sync

**Accounts not linked to contacts**

* Verify contacts have an AccountId in Salesforce
* Ensure the account has a valid website domain
* Check that the account record exists and is not deleted

**Cases missing conversations**

* Make sure "Import Cases to Conversations" is enabled
* Verify your Salesforce edition includes Case support
* Check that the case has a subject or description
* Some conversation features (Live Chat, Messaging) may not be available in all Salesforce editions

**Case messages incomplete**

* BuildBetter automatically detects available features in your org
* If you don't see email messages or live chat, these features may not be enabled in your Salesforce org
* Check Salesforce permissions for accessing FeedItems, EmailMessages, etc.

**Cases I expected aren't being imported**

* Check whether you've enabled the **Case Reason filter** — only Cases matching the selected Reasons are imported
* Add the missing Case Reasons to the filter or clear it to import everything

**Custom Object records not appearing**

* Confirm Custom Object Sync is enabled and the right objects are selected
* Verify the Account relationship field is mapped — records without a linked Account can't be attributed to a BuildBetter company
* Check that the BuildBetter integration user has read access to the custom object and its fields

**Meeting summaries not appearing in Salesforce**

* Verify "Recording Summaries to Contacts" is enabled
* Ensure meeting attendees have email addresses
* Check that the recording has finished processing in BuildBetter
* Verify contacts exist in Salesforce or will be created automatically

### Permission Issues

**"Insufficient permissions" errors**

* Re-authorize the integration to grant all required permissions
* Verify you have API access in Salesforce
* Check that your Salesforce profile allows creating Events
* Ensure you have read access to Contacts, Accounts, and Cases

**Field-level security blocking sync**

* Some custom fields may have field-level security restrictions
* Check Salesforce field accessibility settings
* BuildBetter will sync available fields and skip restricted ones

## Salesforce Editions

**Supported Editions:**

* Enterprise Edition ✅ (Full API access)
* Unlimited Edition ✅ (Full API access)
* Professional Edition ✅ (API access may require add-on)
* Developer Edition ✅ (Limited API calls)

**API Limits:**

* Salesforce enforces daily API call limits based on your edition
* BuildBetter respects these limits and retries when necessary
* Large syncs may take longer if approaching API limits
* Check your Salesforce API usage in Setup → System Overview

## Data Privacy & Security

* All data transferred is encrypted in transit (HTTPS)
* OAuth tokens are securely stored and automatically refreshed
* Only requested scopes are accessed
* Data sync respects Salesforce's field-level security
* BuildBetter never stores your Salesforce password

## Best Practices

**Configure Field Selection**
Choose only the fields you need to reduce sync time and API usage.

**Set Up Sync Rules First**
Configure which data to sync before enabling the integration to avoid syncing unnecessary records.

**Monitor API Usage**
Check your Salesforce API usage regularly, especially if you have a Professional Edition with limited API calls.

**Test with Sample Records**
After connecting, verify that a sample contact, account, and case sync correctly before enabling for all records.

**Use Custom Fields Wisely**
Custom fields will be stored as additional metadata in BuildBetter. Only sync fields you'll actually use.

## Support

Need help with Salesforce integration?

* Check connection status in Settings → Integrations → Salesforce
* Review error messages for specific issues
* Verify Salesforce API limits haven't been exceeded
* Contact BuildBetter support with your Salesforce edition and any error messages