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

# Salesforce integration

> Map Recap fields onto your Salesforce object after every completed call, with an optional follow-up Task. Connected-app auth, your field map, your object.

The Salesforce integration writes Recap outputs back to the record your team
works in: a configurable field map updates the Salesforce object you choose
(Opportunity, Contact, a custom object), and an optional follow-up Task
carries the TL;DR and summary.

## What you need

* A **Salesforce connected app** with OAuth enabled and the `api` and
  `refresh_token` scopes, plus a **refresh token** from the OAuth flow.
* Your **instance URL** (for example,
  `https://yourorg.my.salesforce.com`).
* The **object** to write to (for example, `Opportunity`) and the
  **record-id CRM field** your calls carry to reference the record (the
  default is `salesforce_id`).
* A **field map**: which Recap field writes to which Salesforce field.

## Connect

1. In PyAI Console, open **Integrations** and find **Salesforce** under CRM.
2. Click **Connect** and enter the instance URL, client id, client secret,
   refresh token, object, and record-id field.
3. Define the field map, for example:

```json theme={null}
{
  "tldr": "Description",
  "summary": "Call_Summary__c",
  "next_steps": "Next_Steps__c"
}
```

4. Leave **Create a follow-up Task** on if you want a rep-facing Task with
   the TL;DR and summary after each call.
5. Save. Every completed call writes back from then on; each Recap record
   carries a CRM write status so you can see the result per call.

## Troubleshooting

* **crm\_write\_status: failed:missing\_record\_id.** The call did not carry the
  record-id field (default `salesforce_id`) in its CRM fields. Include it in
  the call metadata, or set `record_id_field` to the key you use.
* **crm\_write\_status: failed:... token.** The refresh token was revoked or
  the connected app changed. Re-run the OAuth flow, update the config
  (omitted secret fields are preserved).
* **crm\_write\_status: skipped:no\_config.** Salesforce is not enabled or the
  field map is empty; complete the config in the console.
* **Field not writable.** A field in your map does not exist or is read-only
  on that object; Salesforce rejects the PATCH and the status shows it. Fix
  the field API name in the map.