> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retellai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# CRM integrations
> Connect Salesforce, HubSpot, Dynamics 365, GoHighLevel, or Zoho to Retell AI: sync contacts both ways, map analysis to fields, and log conversations.
Retell's CRM integration syncs contacts both ways between your CRM and Retell. Import contacts, enrich them with [Post Call Extraction](/features/post-call-analysis-overview) results, and push conversation activity back, all automatically.
CRM is one category of Retell's [integrations](/integrations/overview); this page covers the sync features specific to CRM connections.
## When to use it
Set up contact sync when caller records already live in your CRM and you want agents and the CRM working from the same data. It's the right choice when you want to:
* **Greet callers by name.** Synced contact fields are available to the agent as [dynamic variables](/build/dynamic-variables), so it knows who's calling before the first word.
* **Keep the CRM current without manual entry.** Analysis results from each conversation write back to the CRM record.
* **Keep an activity trail where your team works.** Each call and chat can log to the CRM automatically.
For example, a lead-qualification agency syncs its GoHighLevel contacts into Retell and maps a `qualified` analysis field back to the CRM, so its follow-up workflows trigger from that field after every call — no one touches a record by hand.
If you only need the agent to look up or update CRM records, [integration tools](/integrations/overview#use-integration-tools-in-an-agent) do that without sync.
## Supported CRM platforms
Sync contacts and log call and chat activity as Salesforce Tasks.
Sync contacts and log call and chat activity to the HubSpot timeline.
Sync contacts and log calls as Phone Call activities. Connect with OAuth and your environment URL.
Sync sub-account contacts and log activity as contact notes. Connect with an API key and Location ID.
Sync Contacts and log calls as Call records. Connect with one OAuth sign-in, on any Zoho data center.
## How does the CRM integration work?
The integration has four parts, each configured separately.
### 1. Contact sync (CRM to Retell)
Retell imports contacts from your CRM and keeps them current. Imported records appear on the [Contacts](/features/contacts) page.
* **Phone number** is the key used to match contacts between systems. It's mapped by default and can't be unmapped.
* **Inbound sync mappings** control which CRM fields are imported.
* See [contact fields](#contact-fields) below for the built-in fields and the custom field types you can map.
Sync runs **every 5 minutes** (as of August 2026) and imports only records modified since the last run. A **manual sync re-scans every contact** from scratch, ignoring that cursor, so use it after changing mappings rather than as a routine refresh.
Contacts are skipped when the mapped phone field is empty, or when its value can't be parsed into a valid E.164 phone number. A contact that syncs but shows no name or custom fields usually means those fields aren't mapped, not that the sync failed.
### 2. Post Call Extraction mapping (analysis to contacts)
After each call or chat, Retell can map [Post Call Extraction](/features/post-call-analysis-overview) results onto contact fields, building a richer profile as your agents have more conversations.
Each mapping has an update mode. The dashboard labels these differently on the [contact fields](/features/contacts#define-contact-fields) page:
| Update mode | Dashboard label | Behavior |
| ----------------- | ---------------------- | ------------------------------------------------------------------------------------- |
| **Overwrite** | Overwrite | Always replace the existing value with the new analysis result |
| **Fill if empty** | Fill only if empty | Only write when the field currently has no value |
| **Merge** | Accumulate & summarize | Combine the existing and new values with an LLM (\$0.005 per merge as of August 2026) |
You configure analysis data mappings **per workspace**, not per agent, so the same rules apply no matter which agent handled the conversation.
See [CRM data mappings](/integrations/crm-mappings) for the full data flow and how to write field descriptions so merges produce accurate combined values.
### 3. Outbound field sync (Retell to CRM)
**Outbound sync mappings** push contact field updates from Retell back to your CRM. When a contact's fields change in Retell, whether manually or through analysis mapping, Retell writes the mapped fields to the matching CRM record.
By default, outbound sync **updates existing CRM records only** and never creates or deletes contacts. Turn on **Create new contacts in CRM** on the Sync tab to let Retell create a new CRM record after a conversation when the matched contact isn't linked to one yet. This toggle is off by default; deletion never happens either way.
Unlike contact sync, this isn't on a schedule. Retell pushes changes as they happen: right after a conversation ends, as part of applying its analysis results, or immediately when you edit a contact's fields.
### 4. Conversation activity logging (Retell to CRM)
With **Log activities automatically** enabled, Retell logs each call and chat to your CRM:
* **Salesforce** — a Task record carrying the call duration, with the summary, conversation ID, from and to numbers, and disconnection reason in the description.
* **HubSpot** — a Call engagement, or a Communication object for chats, on the contact's activity timeline.
* **Microsoft Dynamics 365** — a completed Phone Call activity with the direction and duration for calls, or a Task for chats.
* **GoHighLevel** — a note on the contact with the conversation ID, the from and to numbers, and the summary.
* **Zoho CRM** — a Call record with the direction and duration for calls, or a completed Task for chats.
Retell logs activity only for contacts imported from the currently connected CRM. A call from a number that doesn't match a synced contact produces no activity record, and neither do contacts Retell created on its own.
## Set up a CRM integration
Open **Integrations** in the Retell Dashboard, select the **Available** tab, and pick your provider. Follow the provider guide for the credentials:
* [Salesforce setup guide](/integrations/salesforce)
* [HubSpot setup guide](/integrations/hubspot)
* [Microsoft Dynamics 365 setup guide](/integrations/microsoft-dynamics)
* [GoHighLevel setup guide](/integrations/gohighlevel)
* [Zoho CRM setup guide](/integrations/zoho)
Creating a connection requires an Admin or Developer role (see [connect a provider](/integrations/overview#connect-a-provider) for the exact permissions).
After the connection test passes, select **Set up contact sync**. The dialog has two tabs: **Import contacts** (CRM to Retell) and **Sync to \[provider]** (Retell to CRM). Phone number is mapped for you and stays locked.
For CRM fields that don't correspond to a default Retell field, create a custom field in Retell to hold the value. You can do this inline from the mapping dropdown.
Map your [Post Call or Post Chat Extraction fields](/features/post-call-analysis-overview) to contact fields, choosing an update mode for each based on how you want data to accumulate.
Turn on **Log activities automatically** on the **Sync to \[provider]** tab to log each call and chat to your CRM.
Turn on **Create new contacts in CRM** on the same tab to have Retell create a CRM record after a conversation when the matched contact isn't linked to one yet. It's off by default.
Trigger a manual sync to import your existing contacts. This is a full scan, so a large CRM takes a while. It picks up where it left off if it doesn't finish in one pass.
You can connect several CRM accounts, but only one connection drives contact sync for your workspace at a time. The **Contact sync** toggle in a connection's settings decides which one; turning it on for one connection takes sync over from the previous one.
## Contact fields
Every Retell contact has four built-in fields:
| Field | Type | Description |
| -------------- | ------- | ----------------------------------------------------------------------------- |
| `phone_number` | string | Primary identifier for matching contacts across systems |
| `first_name` | string | Contact's first name |
| `last_name` | string | Contact's last name |
| `do_not_call` | boolean | Used for filtering only. It does **not** block outbound calls to the contact. |
Extend contacts with **custom fields** of type `string`, `number`, `boolean`, `date`, `datetime`, or `enum`.
`do_not_call` isn't mapped by default in either direction. Map it explicitly on both tabs if you want it to sync.
## Use contact data in agents
Contact fields are available as **dynamic variables** in your agent prompts. When a call matches a known contact by phone number, Retell injects the mapped contact fields into the agent's context, so your agent can personalize the conversation using CRM data like the contact's name, account status, or history.
See [dynamic variables](/build/dynamic-variables) for how to reference contact fields in a prompt.
## Troubleshooting
A connection is marked as errored when your CRM **rejects the credentials**, such as an expired secret or a revoked token, and whenever the connection test fails. Sync failures caused by a missing field permission or scope leave the connection reading as healthy while that one field or feature quietly stops working. If a specific field or activity type isn't syncing but the connection looks fine, check permissions and scopes on the CRM side rather than the connection itself. The [integrations overview](/integrations/overview#faq) FAQ covers the health model in full, including where GoHighLevel differs.