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

# CRM integrations

> Connect HubSpot or Salesforce in Settings → CRMs to show CRM records beside each session, sync contacts, and give the AI agent CRM fields as context.

**Settings → CRMs** connects your CRM so agents see the customer's CRM record beside each session, and so OpenCX contacts stay in step with the CRM. Use it when your customer data lives in HubSpot or Salesforce and your team works sessions in the OpenCX inbox.

> [!NOTE]
>
> **Settings → CRMs** in your [OpenCX dashboard](https://platform.open.cx/settings/crms). Requires the **Integrations** permission in [Roles](https://docs.open.cx/security/roles.md): **Read** to view, **Write** to connect, disconnect or change settings. This connection is separate from a helpdesk connected in **Settings → Add-ons**, such as the [HubSpot helpdesk integration](https://docs.open.cx/integrations/hubspot/overview.md).

## Which CRMs you can connect

| CRM | How you connect | What you get |
| - | - | - |
| **HubSpot** | A private app access token | A HubSpot card in each session and a one-click contact import |
| **Salesforce** | A Connected App's credentials | A Salesforce card in each session, continuous contact sync, CRM fields on contacts for the AI agent, and Salesforce workflow actions |
| **Pipedrive**, **Zendesk Sell** | Not available for self-service | Selecting **Connect** explains how to ask your account manager. Pipedrive leads can still be updated from workflows: see [Pipedrive](https://docs.open.cx/integrations/pipedrive/overview.md). |

## Connect HubSpot

**1. Create a private app in HubSpot**

In HubSpot, open **Settings → Integrations → Private Apps** and create an app, or pick an existing one. On the **Scopes** tab, enable `crm.schemas.contacts.read`, `crm.objects.contacts.read`, `crm.objects.companies.read`, `crm.objects.deals.read` and `tickets`. Copy the access token.

**2. Connect it**

In **Settings → CRMs**, select **Connect** on **Connect HubSpot**, paste the token into **Access Token** and select **Connect HubSpot**. The row then shows **HubSpot Connected** with your portal ID.

**3. Import contacts (optional)**

Select **Sync contacts** to copy every HubSpot contact into OpenCX contacts with their email, phone and first name. Run it again whenever you want to pick up new HubSpot contacts.

## Connect Salesforce

**1. Create a Connected App in Salesforce**

In Salesforce Setup, open **App Manager** and create a **New Connected App**. Enable OAuth settings, add the `api` scope and check **Enable Client Credentials Flow**. Enter any valid callback URL, such as `https://login.salesforce.com`; it is required but not used.

**2. Choose the user OpenCX acts as**

Under the app's **Manage → Edit Policies**, assign a **Run As** user for the client credentials flow. That user needs API access and read access to Contact, Lead, Account, Opportunity and Case.

**3. Connect it**

Copy the **Consumer Key** and **Consumer Secret** from **Manage Consumer Details**, and your **My Domain URL** from **Setup → My Domain**. In **Settings → CRMs**, select **Connect** on **Connect Salesforce**, fill in the three fields and select **Connect Salesforce**.

Once connected, select **Manage** on the Salesforce row. The dialog has four tabs:

| Tab | What you do there |
| - | - |
| **Connection** | See the connected org and its health. **Sync contacts** runs a full sync now. **Background sync** keeps Salesforce contacts and leads synced every few minutes. **Disconnect** ends the connection. |
| **Attributes** | Turn on **Attribute sync** and pick **Contact fields**, **Lead fields** (up to 50 each) and **Account fields** (up to 20) to copy onto matching OpenCX contacts as attributes. Account fields are stored with an `sf_account_` prefix. |
| **Custom objects** | Show records from up to 10 Salesforce custom objects on the contact's card. For each, pick the **Contact lookup field** that links it to a Contact, the **Fields** to show, and optional **Stamp fields** copied onto the contact as attributes. |
| **Activity** | A log of connection, lookup and sync events, filterable by level and type, to see why something failed |

Synced Salesforce contacts and leads become OpenCX contacts linked to their Salesforce record. When someone edits a linked contact's name, email or phone in OpenCX, the change is written back to the Salesforce Contact or Lead.

## What agents see in a session

Each connected CRM adds a card to the session details panel. Reorder or hide them for everyone under **Session details cards** in [Workspace settings](https://docs.open.cx/ticketing/workspace-settings.md#session-details).

* **HubSpot**: the contact is matched by email, then phone. The card appears only when there is a match. Agents see **HubSpot Contact** (name, email, phone, company and HubSpot ID, with a link to the record), **HubSpot Company**, the latest two **HubSpot Deals** and the last three **HubSpot Tickets**.
* **Salesforce**: OpenCX looks for a Contact by email, then by phone, then for an unconverted Lead the same way. Agents see the matched record with its **Account**, **Opportunities**, **Past cases** and any custom objects you enabled. With no match, the card says **No Salesforce match for this contact** and offers **Create contact** and **Create lead**, which create the record from the contact's details. If Salesforce can't be reached, the card says so instead of reporting no match.

When a phone call rings your agents, OpenCX also fills in the caller's missing name and email from a matching HubSpot or Salesforce record. Values already on the contact are never overwritten.

## What the AI agent gets

* **Salesforce**: fields you choose under **Attributes** and **Stamp fields** are stored on the contact as attributes. The AI agent reads contact attributes as context, within the limits you set in [AI Context](https://docs.open.cx/safety/ai-context.md). Segments can use them too.
* **HubSpot**: this connection gives the AI agent no HubSpot records. **Sync contacts** only creates or updates OpenCX contacts.

Workflows can also act on Salesforce through this connection with **Log Salesforce Activity (CRM)**, **Create Salesforce Case from Session (CRM)** and **Update Salesforce Record (CRM)**. Integrations can read the Salesforce card through the [Salesforce CRM API](https://docs.open.cx/api-reference/integrations/salesforce-crm/get-salesforce-crm-contact.md).

## Disconnect a CRM

Select **Disconnect** on the HubSpot row, or in the Salesforce **Manage** dialog. Disconnecting Salesforce stops every lookup and sync and clears its setup, including synced fields and custom objects. Attributes already stored on your contacts stay, and nothing changes in Salesforce.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| Connecting Salesforce fails right after you created the Connected App | A new or edited Connected App can take a few minutes to become active | Wait a few minutes and try again |
| Salesforce connects but cards are empty | The **Run As** user lacks read access to Contact, Lead, Account, Opportunity or Case | Grant the access in Salesforce, then select **Sync contacts** |
| The Salesforce row shows **Connection failing** | Salesforce rejected the last call; the message is shown under the row | Fix the cause in Salesforce. The status clears after the next successful call. Check the **Activity** tab for details. |
| No HubSpot card on a session | No HubSpot contact matches the contact's email or phone | Check the contact's details, or add them to HubSpot |

***

## Related Documentation

> [card] [HubSpot helpdesk](https://docs.open.cx/integrations/hubspot/overview.md)
>
> Run HubSpot as your helpdesk

> [card] [Salesforce Service Cloud](https://docs.open.cx/integrations/salesforce/overview.md)
>
> Route sessions to Salesforce agents

> [card] [AI Context](https://docs.open.cx/safety/ai-context.md)
>
> Choose which attributes the AI sees

> [card] [Contacts](https://docs.open.cx/contacts/manage-contacts.md)
>
> Manage synced contacts


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.