Connect Salesforce to Beam

Connect your account

A Beam Owner or Admin opens Settings → Integrations → CRMs → Salesforce, selects Connect Salesforce, authorizes Lightmeter, and confirms the connection in Beam. Check the Salesforce organization before confirming. Revenue attribution reads Salesforce data. Positive reply sync is separately configured and enabled.

Administrator setup

A Salesforce administrator must install the Lightmeter app before anyone connects. The Lightmeter app is Lightmeter’s packaged Salesforce External Client App. Open the Lightmeter installation page while signed in to the intended organization, choose Install for Admins Only, tick the acknowledgment box, and select Install. The package contains connection settings only; it adds no objects, fields or code.

Optionally, control who can connect by opening the Lightmeter app’s policies in Salesforce Setup and selecting Edit Policies. Set Permitted Users to Admin approved users are pre-authorized, then add the connecting user’s permission set or profile.

Connect as a user with a standard Salesforce license. API-only users, such as the free Salesforce Integration license, can’t complete the sign-in. The user needs the permissions for the features you use. In Beam, open Settings → Integrations → CRMs → Salesforce and select Connect Salesforce. Salesforce asks you to sign in: choose the user and organization you intend to connect, select Allow, then check the organization and confirm in Beam.

The connecting user needs API Enabled. Revenue attribution requires read access to Contacts, Accounts, Opportunities, Opportunity Contact Roles, and Opportunity history. For Positive reply sync, grant read access to Leads, Contacts, Accounts and their owners, and create/edit access to Leads, Contacts and Tasks, including the fields you map. Account OwnerId must be readable; creating missing Leads also requires a writable Lead Description. The connecting user must be able to assign Tasks to the responsible rep. The existing api OAuth scope supports these writes; no additional OAuth scope is needed. Salesforce editions without API access, including Professional without the API add-on, cannot connect. This connection uses the production Salesforce sign-in page; sandbox authorization is not currently supported.

Revenue attribution

Select the Opportunity stages that count as Qualified (open or won stages) and Closed Won (won stages). Choose what the amounts mean and a reporting time zone; Beam suggests the Salesforce organization's time zone. A monthly target is optional. Save and open Reports → Revenue.

Beam matches people Lightmeter emailed to Contacts by exact email address. Opportunity Contact Roles link those Contacts to Opportunities. Account fallback includes only Opportunities with no Contact Roles at all, excluding Opportunities linked to another Contact. Each Opportunity is attributed once under the existing Revenue attribution rules.

Stage entry dates come from Opportunity history. Missing history stays missing; the current stage and Close Date do not supply a stage entry date. Stage choices are one list of active stages; record types and sales processes are not separate pipelines. If a saved stage is removed or no longer eligible, update Revenue settings.

Opportunity Amount is one one-off amount, in the Opportunity currency for a multi-currency organization and the organization's currency otherwise. Beam does not convert currencies. A missing amount remains Amount missing. Weighted amounts use the Opportunity probability.

Positive reply sync

Select Positive reply sync, configure the fields, save, and check the connection. Turn on the capability to sync qualifying Positive conversations. An exact email address must identify a single Contact or unconverted Lead. Multiple matches block delivery for review. With Create a Lead when no Contact or Lead matches selected, map Company and any other required Lead fields. Otherwise, a missing match blocks delivery.

Field choices come from your Salesforce organization. Choose Do not set this field to omit an optional field. Existing records keep their values unless you explicitly select Update existing records. Contact mappings require this option because Beam never creates Contacts. Email identity, ownership, Account association and suppression fields cannot be mapped. Beam never reassigns a Contact or Lead.

A completed Task stores the bounded email thread. It uses TaskSubtype=Email when Salesforce exposes that option as createable; otherwise it is a plain completed Task. Setup shows the completed status used for the log: Completed is preferred, then the default closed status, then the first closed status. Later conversation changes update that same log, even if the original rep has since become inactive. A separate open Task, Lightmeter: positive reply from {name}, goes to the Contact’s Account owner, or to the Contact/Lead owner when no Account applies. An unavailable, inactive or queue owner blocks follow-up rather than routing to a different person. Existing Tasks are not reassigned or reopened.

Send a test reply to Salesforce is optional. Review the selected conversation before confirming: this writes records and applies your saved mappings, but sends no email. You can activate without a successful test; the status then shows Untested. Each created record carries a conversation marker. After an uncertain create, retrying reconciles that marker before creating anything: one match is reused, no matches allow creation after a twelve-minute reconciliation window, and ambiguous results remain unresolved. Automatic delivery retries while waiting for confirmation and after temporary Salesforce failures. Only ambiguous matches require resolution. Updates to existing records can be safely retried; a deleted email-log Task is recreated through the same marker check. Salesforce email observation is not available.

If an optional test is interrupted, select Check test result, then Resume test. Beam checks Salesforce for the earlier attempt before writing and keeps the original checkpoint. Starts and resumes share the ten-attempt hourly limit per integration. Resume includes newer Positive replies in the same conversation while requiring the same recipient. API: POST /api/v1/settings/crm-integration/salesforce/test-conversation-operations/resume with the original operation ID and preview payload. MCP: workspace_crm_conversation_test_resume with provider salesforce. Automatic deliveries marked indeterminate also offer Retry reply in Settings, using the same reconciliation rules.

Blocklist sync

Select Salesforce to Beam, Beam to Salesforce, or Two-way. Save settings, preview the import and approve the current preview before activation. This approval is required again after pausing. Outbound-only previews show zero imported addresses. Optional positive reply tests are independent of Blocklist activation.

Imports read Contact and unconverted Lead HasOptedOutOfEmail and DoNotCall. Either flag adds the record's email to the workspace Blocklist; DoNotCall is a calling block, not an email-consent flag. Clearing either flag never automatically removes a Beam block. Imports save each page and resume after temporary failures.

Exports apply reply opt-outs to a single exact-email Contact or unconverted Lead, setting both flags to true. No record is created. Missing and ambiguous matches are skipped for review. Imported blocks do not produce export loops. If access or identity needs correction, fix it in Salesforce and select Retry Blocklist sync; only enabled directions retry. Pause Blocklist sync before changing its direction, then save and approve a fresh preview.

Administrators: allow read access to Email, HasOptedOutOfEmail and DoNotCall on both Contact and Lead. Exports also require edit access to HasOptedOutOfEmail and DoNotCall on both objects. The Lightmeter app’s existing api scope permits these writes. No Task or Lead-create permission is needed for Blocklist-only setup.

Use the same settings PUT with blocklist_selected and blocklist_direction (salesforce_to_beam, beam_to_salesforce, two_way). POST .../salesforce/blocklist-preview, then .../salesforce/blocklist-preview/approve with configuration_revision. Activate or disable capability blocklist_sync through the existing capability endpoints. POST .../salesforce/blocklist/retry retries blocked work in the enabled directions, excluding expected missing matches; export retries are limited to once per minute per delivery. If DoNotCall access is lost after activation, email opt-outs continue while calling blocks wait for access to be restored. MCP uses workspace_crm_update, workspace_crm_blocklist_preview, workspace_crm_blocklist_approve, workspace_crm_capability_activate, workspace_crm_capability_disable and workspace_crm_salesforce_blocklist_retry, with provider salesforce and identical revisions and permissions.

Reconnect or disconnect

If access expires or is revoked, use Reconnect Salesforce. Beam renews quiet connections automatically. Disconnect in Lightmeter to revoke access at Salesforce and delete stored credentials; Salesforce records and saved Revenue settings remain. You can also uninstall the Lightmeter package in Salesforce Setup → Installed Packages.

API and MCP

Read connection state with GET /api/v1/settings/crm-integration/salesforce or workspace_crm_salesforce_get. MCP workspace_crm_create with provider: salesforce opens the authenticated browser connection flow; credentials are never supplied to MCP.

Read or save Revenue settings through GET or PUT /api/v1/settings/crm-integration/revenue-setup?provider=salesforce, or workspace_crm_revenue_setup_get and workspace_crm_revenue_setup_update with provider: salesforce. Disconnect through POST /api/v1/settings/crm-integration/salesforce/oauth/disconnect or workspace_crm_oauth_disconnect, supplying the current configuration and OAuth grant revisions. API keys need the settings-management grant for changes; workspace permissions apply throughout.

Positive reply settings and discovery use GET /api/v1/settings/crm-integration/salesforce/sync, GET .../salesforce/discovery, and PUT .../salesforce. The PUT body contains configuration_revision from the current sync status and settings: positive_reply_selected, create_missing, lead_fields and contact_fields. Each mapping has field, a scalar value, and optional update_existing. Settings replace the saved configuration; stale revisions are rejected.

Use POST .../salesforce/validate to check access and POST .../salesforce/capabilities/positive_reply_sync/activate with the current configuration revision to activate. Disable with POST .../salesforce/capabilities/positive_reply_sync/disable. Optional tests use GET .../salesforce/test-conversation-preview?conversation_id={id}, then POST .../salesforce/test-conversation-operations with an operation ID and the returned preview fields; read its durable outcome with GET .../salesforce/test-conversation-operations/{operation_id}.

MCP exposes workspace_crm_salesforce_sync_get and workspace_crm_salesforce_metadata_get, plus the shared workspace_crm_update, workspace_crm_validate, workspace_crm_capability_activate, workspace_crm_capability_disable, workspace_crm_conversation_preview, workspace_crm_conversation_test_start, workspace_crm_conversation_test_get and workspace_crm_conversation_retry tools with provider: salesforce. The UI, public API and MCP enforce the same workspace permissions and test-preview validation.