> ## 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.

# Salesforce contact sync

> Sync Salesforce Contacts with Retell AI: phone-matched field mappings, post-call analysis write-back, and calls and chats logged as Salesforce Tasks.

Contact sync imports your Salesforce Contacts into Retell, writes [post-call analysis](/features/post-call-analysis-overview) results back to their fields, and logs every call and chat as a Salesforce Task on the matched Contact. This page covers the Salesforce-specific behavior; [CRM integrations](/integrations/crm-overview) explains the four data flows all CRM providers share.

Contact sync requires a [connected Salesforce org](/integrations/salesforce). Integration tools work without it — see [Salesforce agent functions](/integrations/salesforce-functions).

## Required permissions

Sync runs as the Run As user, set up in [Step 4 of connecting](/integrations/salesforce#step-4-set-the-run-as-user). Its profile or permission sets need:

* **API Enabled**.
* **Read** on Contact and on every field you import.
* **Edit** on Contact and on every field you write back, if you enable outbound sync.
* **Create** on Task, if you enable activity logging.

A missing object or field permission doesn't flag the connection; that field or feature silently stops syncing.

## Set up contact sync

After the connection test passes, click **Set up contact sync** to open the field mapping dialog, then map the Salesforce fields you want to import and the Retell fields you want to write back. For a connection made earlier, the same dialog opens from the **Connected** tab: open the connection's settings and click **Set up contact sync**.

Retell pre-fills one mapping in each direction: Salesforce `Phone` to Retell `phone_number`. Phone number is how contacts are matched between the two systems, so it stays mapped and can't be removed. See [CRM data mappings](/integrations/crm-mappings) for how to map the rest, create custom fields, and choose update modes.

To log conversations to Salesforce, turn on **Log activities automatically** on the **Sync to Salesforce** tab.

## Verify it worked

* Open **Contacts**. After the first sync, Salesforce Contacts appear with correctly formatted phone numbers and your mapped fields populated.
* The first sync is a full scan of every Contact that has the mapped phone field, so a large org takes a while. After that, Retell polls every 5 minutes (as of August 2026) and imports only Contacts modified since the last run.

<Note>
  Contacts with no value in the mapped phone field are skipped, as are Contacts whose number can't be parsed into a valid E.164 number. Fix or remove malformed numbers in Salesforce before relying on two-way sync.
</Note>

## How are calls and chats represented in Salesforce?

Both become Task records associated with the matched Contact through `WhoId`, with `Status` set to `Completed`. A call uses the `Call` task subtype, a subject of `Call <call_id>`, and sets `CallDurationInSeconds`. A chat uses the generic `Task` subtype, since Salesforce has no standard chat or SMS subtype. The description carries the conversation ID, the from and to numbers, the disconnection reason for calls, and the summary.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sync runs clean but one field never populates">
    A permission error on a single field doesn't fail the sync or flag the connection, because Retell only treats credential rejections as connection errors. Check that the [Run As user's](/integrations/salesforce#step-4-set-the-run-as-user) profile or permission set grants read (and edit, for outbound) on that specific field, and that the field is mapped on the right tab of the sync settings.
  </Accordion>

  <Accordion title="Calls aren't showing up as Tasks in Salesforce">
    Activity logging needs three things: **Log activities automatically** enabled on the **Sync to Salesforce** tab of the sync settings, a Retell contact that was imported from this Salesforce connection, and **Create** permission on Task for the [Run As user](/integrations/salesforce#step-4-set-the-run-as-user). Retell attaches the Task to the Contact it matched by phone number, so a call from a number that isn't a synced Salesforce Contact is never logged.
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Does Retell create new Contacts in Salesforce?">
    Only if you opt in. By default, outbound sync updates Contacts that already exist in Salesforce and never creates or deletes them. Turn on **Create new contacts in CRM** on the **Sync to Salesforce** tab to have Retell create a Salesforce Contact after a conversation when the matched contact isn't linked to one yet. With the toggle off, contacts Retell creates on its own (for example from an inbound call from an unknown number) stay in Retell and aren't pushed to Salesforce.
  </Accordion>

  <Accordion title="Which Salesforce objects does contact sync read?">
    Only `Contact`. Leads, Accounts, Opportunities, Cases, and custom objects are not part of contact sync — the [integration tools](/integrations/salesforce-functions) reach those objects live instead.
  </Accordion>

  <Accordion title="Can I map custom fields?">
    Yes. Map any Salesforce Contact field, including `__c` custom fields, to a Retell [custom field](/integrations/crm-mappings#custom-fields).
  </Accordion>

  <Accordion title="What happens to my Retell contacts if I disconnect?">
    They stay. Turning contact sync off stops future syncs, and deleting the connection removes the stored credentials. Contacts already imported remain in Retell either way.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="CRM data mappings" icon="arrows-left-right" href="/integrations/crm-mappings">
    Map Salesforce fields to Retell contacts, choose update modes, and control what syncs back.
  </Card>

  <Card title="Build contact memory" icon="brain" href="/integrations/build-contact-memory">
    Accumulate what your agents learn across conversations into the contact record.
  </Card>

  <Card title="Dynamic variables" icon="code" href="/build/dynamic-variables">
    Reference synced contact fields from your agent's prompt.
  </Card>

  <Card title="Salesforce agent functions" icon="wrench" href="/integrations/salesforce-functions">
    Look up the caller, read opportunities and cases, and create leads and tasks mid-conversation.
  </Card>
</CardGroup>