Data Model Overview
The CRM integration involves three main entities and four data flows between them:External CRM
Your Salesforce or HubSpot contact records with their native fields.
Retell Contact
A unified contact record in Retell with default fields and custom fields.
Post-Call Analysis
Structured data extracted from each call/chat by your post-call analysis configuration.
| Data Flow | Direction | Description |
|---|---|---|
| Inbound Sync | External CRM → Retell Contact | Import and update contacts from your CRM on a recurring schedule |
| Analysis Mapping | Post-Call Analysis → Retell Contact | Map extracted conversation data to contact fields after each call/chat |
| Outbound Sync | Retell Contact → External CRM | Push updated contact fields back to your CRM |
| Activity Logging | Retell Contact → External CRM | Log call and chat records as activities on the CRM contact |
How Data Flows
1. Inbound Sync: CRM to Retell
Inbound sync imports contacts from your CRM into Retell. Matching logic: Contacts are matched between systems using phone number as the primary key. When Retell finds a CRM contact with a phone number that matches an existing Retell contact, it updates the existing record. Otherwise, it creates a new contact. Inbound sync mappings control which CRM fields are imported:| CRM Field (Example) | Direction | Retell Field |
|---|---|---|
Phone (Salesforce) / phone (HubSpot) | CRM -> Retell | phone_number (required) |
FirstName / firstname | CRM -> Retell | first_name |
LastName / lastname | CRM -> Retell | last_name |
Default Field / hs_field | CRM -> Retell | Your custom field name |
Custom_Field__c / custom_property | CRM -> Retell | Your custom field name |
The
phone_number mapping is required and hardcoded for inbound sync. Without it, Retell has no way to match CRM records to Retell conversations.2. Analysis Data Mapping: Analysis to Contact
After each call or chat, post-call analysis extracts structured data from the conversation. You can map these analysis results to contact fields, building a richer contact profile over time. For example, if your post-call analysis extracts alead_qualification_status field, you can map it to a custom contact field so each contact’s qualification status is automatically updated after every conversation.
Example mappings:
| Analysis Data Field | Direction | Contact Field | Update Mode |
|---|---|---|---|
lead_status | Analysis -> Contact | qualification_status | Overwrite |
email_address | Analysis -> Contact | email | Fill if empty |
customer_notes | Analysis -> Contact | interaction_summary | Merge |
Update Modes
Each analysis data mapping has an update mode that controls how the new value interacts with the existing value:Overwrite
Always replace the existing value with the new analysis result. Use this for fields where the latest value is always the most relevant (e.g., sentiment, status).
Fill if Empty
Only write the new value if the field is currently empty. Use this for fields you want to capture once and preserve (e.g., email address, company name).
Merge
Intelligently combine the existing and new values using LLM. Only available for string fields. Use this for cumulative fields where you want to preserve context from previous conversations (e.g., interaction notes, preferences).
3. Outbound Sync: Retell to CRM
When a contact’s fields are updated in Retell — either manually or via analysis data mapping — the changed fields can be pushed back to your CRM through outbound sync mappings. Outbound sync only triggers when:- The contact has an
externalId(i.e., was originally imported from the CRM) - There is an active connected CRM app
| Retell Field | Direction | CRM Field (Example) |
|---|---|---|
qualification_status | Retell -> CRM | Lead_Status__c / lead_status |
interaction_summary | Retell -> CRM | Notes__c / notes |
4. Conversation Activity Logging
When enabled, Retell logs each call and chat as an activity record in your CRM, associated with the matched contact. This gives your sales team a complete conversation history directly in the CRM. Activity records include:- Call/chat direction (inbound or outbound)
- Duration (for calls)
- Summary
- Timestamp
End-to-End Data Flow Example
Here’s how a typical interaction flows through the system:Contact imported from CRM
An inbound sync imports a contact from Salesforce with fields:
Phone: +1234567890, FirstName: Alice, LastName: Smith, Lead_Status__c: New.A Retell contact is created with: phone_number: +1234567890, first_name: Alice, last_name: Smith, lead_status: New.Agent makes a call
Your voice agent calls Alice. During the call, contact fields are injected as dynamic variables, so the agent knows Alice’s name and lead status.
Post-call analysis runs
After the call, post-call analysis extracts:
lead_qualification_status: Qualifiedcustomer_notes: Interested in enterprise plan, wants demo next weekemail: alice@example.com
Analysis data maps to contact
The analysis results are applied to Alice’s contact based on your mappings:
lead_statusis overwritten withQualifiedinteraction_summaryis merged with the new notes, preserving previous conversation contextemailis filled (was previously empty)
Outbound sync pushes to CRM
Updated fields are synced back to Salesforce:
Lead_Status__cupdated toQualifiedNotes__cupdated with the merged interaction summary
Configuring Field Mappings
Custom Fields
Before you can map CRM fields to non-default Retell fields, you need to create custom fields on your Retell contacts. Custom fields support the following types:| Type | Example Values |
|---|---|
string | "Interested in enterprise plan" |
number | 42, 99.5 |
boolean | true, false |
date | 2025-03-15 |
datetime | 2025-03-15T10:30:00Z |
enum | One of a predefined set of options |
Custom field names must be in
snake_case and cannot conflict with the built-in field names (phone_number, first_name, last_name, do_not_call).Field Type Compatibility
When configuring sync mappings, the CRM field type must be compatible with the Retell field type. Retell handles type coercion automatically:- CRM date strings are parsed into Retell
date/datetimefields - CRM picklist values map to Retell
enumfields - CRM numeric strings are converted to Retell
numberfields - CRM boolean-like values (
"true","false") are converted to Retellbooleanfields
Best Practices
-
Start with essential mappings. Map
phone_number,first_name, andlast_namefor inbound sync first. Add custom fields incrementally as you identify what data is valuable. - Use “Fill if empty” for stable data. Fields like email address or company name rarely change — use “Fill if empty” to capture them on first mention without overwriting later.
- Use “Merge” sparingly. The merge update mode uses AI to combine values, which works well for free-text notes but adds latency and cost. Use “Overwrite” or “Fill if empty” when possible.
- Use “Overwrite” for status fields. Fields like lead status or sentiment should always reflect the most recent conversation.
- Enable activity logging for sales visibility. Your sales team can see the full conversation history in the CRM without switching to the Retell dashboard.
- Use a dedicated CRM integration user. For Salesforce, use a dedicated service account as the Run-As user to avoid permission issues when team members change roles.