Documentation CRM Salesforce

CRM integration

Salesforce

Salesforce integration overview
  • CategoryCRM
  • AuthOAuth
  • Scopes2

Overview

Salesforce connects on /integrations in the MessageMind dashboard. Click the Salesforce card and the "Connect Salesforce" modal asks for your Client ID (Consumer Key) and Client Secret (Consumer Secret) from a Salesforce Connected App you own. Clicking integrate navigates to the server's /v1/integration/salesforce/connect endpoint, which starts an OAuth 2.0 authorization-code flow (PKCE, HMAC-signed state) against your Salesforce org and bounces the browser back to /integrations with the result. The shipped sync behind the connection is Product2 only: once authorized, MessageMind subscribes to your org's Change Data Capture stream and mirrors Product2 creates, updates and deletes into the AI's product catalog. The standard connection is a product-catalogue sync. Separate account-specific Contact workflows require confirmation from MessageMind; this does not make Lead or Opportunity writes generally available.

What MessageMind can do with it

  • Mirror your Salesforce Product2 catalog into the AI's product knowledge so the AI can quote and discuss what you actually sell.
  • React to Salesforce Change Data Capture events on Product2 so a product created, updated or deleted in Salesforce is reflected in the AI's catalog within seconds.
  • Separate simple products from variations and variation parents based on Salesforce's ProductClass so variant catalogs stay organized.
  • Respect field-level nulling: when a Salesforce change event explicitly clears a field, the AI's copy of that field is cleared too.
  • Scope the connection to a specific org (production login.salesforce.com, a sandbox host, or a My Domain) so a multi-org admin can keep tenants separate.

Requirements

  • A Salesforce organization with permission to create a Connected App and issue OAuth client credentials.
  • A Connected App configured with the OAuth scopes 'api' and 'refresh_token' and a callback URL that matches MessageMind's redirect URI (${BASE_URL}/v1/integration/salesforce/callback on the server you connect to).
  • Change Data Capture enabled for Product2 in your Salesforce org. Without CDC, product changes made in Salesforce never reach MessageMind.
  • The MessageMind AI model category set to 'eCommerce for Physical Goods' or 'Services'. Any other category causes the Salesforce handler to refuse incoming product events.
  • A MessageMind plan on Starter, Professional or Enterprise. The Salesforce card is plan-gated in /integrations.

How to connect

  1. In Salesforce, go to Setup, App Manager, New Connected App. Enable OAuth, add the scopes 'api' and 'refresh_token', and set the callback URL to MessageMind's redirect URI (/v1/integration/salesforce/callback on the server you connect to). Save and copy the Consumer Key and Consumer Secret.
  2. Enable Change Data Capture for Product2 in Setup, Change Data Capture. Without this step, product changes in Salesforce never flow into MessageMind.
  3. In the MessageMind dashboard, open /integrations and click the Salesforce card. The 'Connect Salesforce' modal opens with the description 'Connect Salesforce so MessageMind can sync leads, contacts, opportunities, and trigger automations based on CRM activity.' (See limitations: the shipped sync is Product2 only.)
  4. Paste your Consumer Key into the Client ID field and your Consumer Secret into the Client Secret field. If either is blank, the modal shows 'Please provide both Client ID and Client Secret.' and nothing is sent.
  5. Click Integrate. The browser navigates to /v1/integration/salesforce/connect on the MessageMind server, which signs an HMAC state value and redirects to Salesforce for sign-in and consent.
  6. Approve access in Salesforce. The server exchanges the authorization code for an access token, refresh token and instance URL, then redirects back to /integrations with ?salesforceSuccess=true. The dashboard toast reads 'Salesforce connected successfully'. On a failure the URL carries ?salesforceSuccess=false and the toast reads 'Failed to connect Salesforce'.

Authentication and permissions

Mechanism
OAuth 2.0 authorization code flow with PKCE (code_challenge S256). A per-connection, HMAC-signed state value (OAUTH_STATE_SECRET) protects the callback against CSRF. The authorization request is tied to a specific Salesforce domain (login.salesforce.com for production by default, a sandbox host, or a custom My Domain).
Credentials
Consumer Key (stored as Client ID on the integration record), Consumer Secret (stored as Client Secret), the redirect URI from your Salesforce Connected App, and after the OAuth exchange the access token, refresh token, instance URL and issued-at timestamp. Tokens are scoped to the Salesforce org that authorized them.

Required scopes

  • api
  • refresh_token

Available data and actions

Reads

  • Salesforce Product2 records delivered through Change Data Capture (Name, Description, ProductCode, Family, IsActive and ProductClass).

AI agent use cases

  • Let the AI quote accurate product names, SKUs and categories inside a chat without the operator having to maintain a second product list.
  • Keep the AI's catalog in sync automatically when a Salesforce admin adds a product, retires one, or edits a product's description.
  • Keep simple products and product variations in their own buckets so the AI can speak about a parent and its variants correctly.

Configuration

  • The MessageMind AI model must be configured with the category 'eCommerce for Physical Goods' or 'Services'. The Salesforce sync routes products into category-specific buckets (simple vs variable, plus a grouped bucket for physical goods) based on this setting.
  • Products with ProductClass set to 'Variation' or 'VariationParent' are routed to the variable bucket. Everything else (including blank ProductClass) is treated as a simple product.
  • The sync debounces writes to the AI model document (changes are coalesced before being persisted) so a burst of Salesforce events does not fan out into one write per event.

Example workflows

Create a product in Salesforce and surface it to the AI

  1. An admin creates a Product2 record in Salesforce with Name, Description, ProductCode, Family, IsActive and (optionally) ProductClass.
  2. Salesforce Change Data Capture emits a CREATE event for the Product2 record.
  3. MessageMind reads the event, classifies the product as simple or variable from ProductClass, and upserts it into the AI model's product bucket for your category.
  4. The AI can now reference the new product by name, SKU and category inside customer conversations.

Delete a product in Salesforce

  1. An admin deletes a Product2 record in Salesforce.
  2. Salesforce emits a DELETE change event with the Product2 record id.
  3. MessageMind removes the product from every product bucket on the AI model so the AI stops offering it.

Limitations

  • The standard Salesforce connection syncs Product2. A separately configured account-specific Contact workflow also exists; confirm availability with MessageMind before relying on contact writes. Accounts, Leads and Opportunities are not part of the standard catalogue workflow.
  • The product sync is read-only from the AI's side: MessageMind does not create, update or delete products in Salesforce.
  • If the AI model's category is not 'eCommerce for Physical Goods' or 'Services', Salesforce product events are rejected and nothing is written to the catalog.
  • Change events must come from Salesforce Change Data Capture. If CDC is not enabled for Product2, changes made in Salesforce will not reach MessageMind.

Troubleshooting

The modal shows 'Please provide both Client ID and Client Secret.' as soon as you click Integrate.

Either field is empty or whitespace-only. Paste both values from your Salesforce Connected App (Setup, App Manager, Manage Consumer Details).

The browser bounces back to /integrations with ?salesforceSuccess=false and a 'Failed to connect Salesforce' toast.

Confirm the Connected App's callback URL matches MessageMind's redirect URI exactly (/v1/integration/salesforce/callback on the connected server), that the Consumer Key and Consumer Secret are current, and that the Connected App has the 'api' and 'refresh_token' scopes enabled. Complete the Salesforce consent step within ten minutes of starting the flow; the authorization code expires after that window.

The dashboard shows 'Salesforce connection failed!' and never reaches Salesforce.

The browser could not reach the MessageMind server's /v1/integration/salesforce/connect endpoint. Check your network and retry; this toast is thrown before Salesforce is contacted.

A product edited in Salesforce does not appear or update in MessageMind.

Check that Change Data Capture is enabled for Product2 in your Salesforce org (Setup, Change Data Capture, Entities). Without CDC the integration has no way to learn about the change.

Products are coming through but the sync is rejecting them.

The AI model must have its category set to 'eCommerce for Physical Goods' or 'Services'. Any other category causes the Salesforce handler to refuse the event.

Disconnect and reconnect

  • In the MessageMind dashboard, open /integrations and disconnect the Salesforce card. The stored access token, refresh token, Client ID and Client Secret are removed from your tenant.
  • In Salesforce Setup, App Manager, open the MessageMind Connected App and click Revoke on the OAuth session to invalidate access on Salesforce's side.
  • To reconnect, click the Salesforce card again on /integrations and paste a fresh Client ID and Client Secret. Previously synced products stay on the AI model until a new sync or a manual edit replaces them.