Skip to main content

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.

​
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

1

Navigate to Integrations

Go to Settings → Integrations in BuildBetter and find Salesforce in the CRM category.
2

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

Connect Your Account

Click Connect to start OAuth authorization, sign in to Salesforce, and approve the permissions BuildBetter needs to sync your data.
4

Configure Sync Settings

After connecting, choose which data to sync (see Configuration Options below).
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.

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

​
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