Manage the people your Retell agents call and text: contact records keyed by phone number, custom contact fields, post-call data mappings, and CRM sync.
Contacts is your workspace’s record of the people your agents talk to. Each contact is keyed by phone number and collects the conversations you’ve had with that person, along with any fields you choose to store about them. Those fields reach the agent as dynamic variables on the next phone call, so it can open with what it already knows instead of asking again.Open it from the Contacts tab under Data in the dashboard.
The Contacts page, showing each contact's conversation count and last conversation.
Your CRM is the source of truth. Sync contacts in from Salesforce or HubSpot and map their fields to agent variables once, instead of passing the same values on every API call.
Conversations span more than one call. When a long call drops or the person calls back, the agent picks up with the context from last time rather than restarting discovery.
You run follow-up or chase sequences. The next call can act on what the last one produced.
You want one set of fields across agents. Post-call data mappings are set per workspace, not per agent, so every agent writes to the same contact fields.
A tutoring company runs 20-minute enrollment calls. They store program_interest, budget_range, and last_topic_discussed as contact fields, filled from post-call analysis. When a prospect calls back after a dropped call, the agent already has all three and resumes at the pricing conversation instead of starting over.
Contacts arrive three ways, and all of them match on phone number:
Automatically, after a conversation. When a phone call or SMS chat ends, Retell looks up the number (the caller’s number on inbound, the number you dialed on outbound). If no contact matches, it creates one, then updates the contact’s conversation count and last-conversation time. Web calls and web chats have no phone number, so they don’t create contacts.
Manually, from Actions → Add contact.
From your CRM, if you’ve connected Salesforce or HubSpot and configured inbound sync.
A phone number identifies exactly one contact. Adding a contact whose number already exists fails with “A contact with phone number +14155551000 already exists.”
Everything on the Contacts page that changes data lives in the Actions menu.
1
Open the form
Select Actions → Add contact.
The Add Contact form, with the workspace's custom fields below the built-in ones.
2
Enter the phone number
Required, and it has to be a valid number. Use E.164 format, for example +14155552671. This is the key everything else matches on.
3
Fill in the rest
First name, last name, and Do not call are optional, as are any custom fields you’ve defined. Custom field values are checked against the field’s type, so a number field rejects text and an enum field rejects values outside its options.
4
Create
Select Create. The contact appears in the table right away, with no conversations attached until one happens.
The table lists every contact in the workspace with these built-in columns, plus one for each custom field you’ve defined:
Column
What it shows
Phone Number
The contact’s number, and the key used to match conversations.
First Name / Last Name
Set manually, synced from your CRM, or written by post-call analysis.
Contact ID
The record’s identifier, for example contact_9f2c41ab77de05c3aa61e480.
Related Conversations
How many calls and chats are attached to this contact.
Latest Conversation
When you last spoke to them.
Do Not Call
A flag you can set, filter on, and sync with your CRM.
External ID
The record ID in the connected CRM, when the contact came from one.
The settings icon above the table, labelled Manage table, controls which columns appear and in what order. The arrangement is saved for the workspace, so everyone sees the same table.Search matches phone number, first name, last name, external ID, and custom field values.Filters narrow by phone number, external ID (including whether one exists at all), do-not-call, last conversation time, and any custom field.
Contact information lists every field on the record and lets you edit them in place. Saving an edit on a CRM-linked contact also pushes the change back to your CRM, if outbound sync is configured.
Conversations lists the calls and chats attached to that number, newest first, with total time and a split of inbound calls, outbound calls, and messages. Selecting one opens the full session.
Use the up and down arrow keys to step through contacts without closing the panel.
A contact's fields on the left, every call and chat with that number on the right.
Beyond the built-in fields, you can define custom fields to store anything else you want to keep about a person. Open Actions → Manage contact fields.The fields table shows, for each field, its type, the CRM field it syncs with, the post-call analysis field that writes to it, and when it last changed.
Contact fields, with CRM sync and post-call mappings shown per field.
1
Add the field
Select Add Contact Field, then pick a type: Text, Number, Boolean, Selector, Date, or Datetime. Type is fixed after creation, so choose deliberately.
Adding a contact field. The type can't be changed once the field exists.
2
Name it
Field names are snake_case: lowercase letters, numbers, and underscores, starting with a letter. Names can’t collide with the built-in fields, can’t start with contact or external (both reserved), and can’t repeat an existing field.
3
Describe what it holds
The description tells you what the field captures. It does more than document: for fields filled by post-call analysis with Accumulate & summarize, the description is the instruction the model follows when combining an old value with a new one.
4
Map it to post-call data (optional)
Turn on the post-call mapping, choose the analysis field that feeds it, and pick how new values combine with existing ones:
Overwrite replaces the stored value every time.
Fill only if empty writes once and leaves it alone after that.
Accumulate & summarize merges the old and new values with a model, following your field description.
Mappings apply to the whole workspace, so any agent producing that analysis field writes to this contact field. See CRM data mappings for the full picture, and contact memory for building running context this way.
Built-in fields behave differently from custom ones. First name, last name, and do-not-call can be edited and mapped, but not deleted. Phone number is fixed. Custom fields can be edited or deleted.
When a phone call starts, Retell looks up the contact by number and passes its fields to the agent as dynamic variables: first_name, last_name, do_not_call, and one per custom field, each named after the field. Reference them in the prompt the same way as any other dynamic variable, for example {{first_name}}.This applies to inbound calls, outbound calls, and batch calls. Chats update contacts after they end, but don’t receive contact fields as variables. If no contact matches the number, the variables are simply absent, so write prompts that read naturally without them.
New mappings only apply going forward. To apply one to conversations that already happened, select Actions → Backfill from Post-Call Data, choose which fields to fill, and scope the run by agent and call time.
Backfilling contact fields from conversations that already happened.
A few things to know before you start:
You need at least one post-call data mapping configured, or the run is rejected.
One backfill runs at a time per workspace. Starting a second returns “A backfill job is already running.”
Progress shows as a banner on the Contacts page while the job runs.
With Salesforce or HubSpot connected, contacts sync both directions: CRM records flow in as contacts, and edits flow back out. Two entries in the Actions menu control it, both disabled until a CRM is connected:
Manage CRM sync opens the field mapping settings. See CRM data mappings.
Run full sync re-imports the full contact set instead of waiting for the next scheduled sync.
While two-way sync is active, contacts that came from the CRM are locked against deletion, so the CRM stays the source of truth for those records.
Contacts needs CRM view permission to open, and CRM edit permission for anything that changes data: adding contacts, editing fields, running a backfill, or triggering a full sync. Without edit permission the controls are visible but disabled. See Access Control.
Contacts are managed in the dashboard. There’s no public API for creating or listing them at the moment.
No. Contacts come from CRM sync, from adding them in the dashboard, or automatically after a conversation. If your contacts live in Salesforce or HubSpot, connect the CRM and let inbound sync bring them in.
Why do contacts appear that I never added?
Ending a phone call or SMS chat with a number that has no contact creates one. That’s what links a conversation to a person and lets the next call reuse what the last one learned.
Can two contacts share a phone number?
No. The number is the identifier, and creating a duplicate is rejected.
Why doesn't a contact show a conversation I know happened?
Conversations attach by phone number, so check that the number on the call matches the contact exactly. Web calls and web chats carry no phone number and never attach to a contact.
Can I delete a contact?
The dashboard doesn’t offer contact deletion today. You can clear a contact’s field values by editing it, and you can delete custom contact fields from the contact fields page. Contacts synced from a CRM are locked against deletion while two-way sync is active.
What happens to my contacts if I disconnect the CRM?
The contacts stay. They keep their fields and their conversation history, and the External ID showing where they came from. Syncing stops, so later changes on either side no longer cross over.
