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

# Troubleshooting CRM Sync and Integration Issues in Piper AI

> Resolve CRM sync problems in Piper AI — notes not syncing, fields not updating, deal linking failures, broken connections, and Aircall issues.

Piper AI syncs meeting notes, structured CRM fields, and tasks directly to your CRM after every call. When a sync doesn't behave as expected, the cause is almost always one of a small set of configuration issues — a missing contact match, a deal that hasn't been linked, or an authentication token that needs refreshing. Work through the scenarios below to identify and fix the problem.

<Accordion title="My notes aren't syncing to the CRM">
  Piper only syncs notes to your CRM when it can match at least one call participant to an existing contact record.

  <Steps>
    <Step title="Check for a contact match">
      Verify that at least one person who attended the meeting exists as a **Contact** in your CRM. Piper uses email address to match attendees to contacts.
    </Step>

    <Step title="Create the contact if it doesn't exist">
      If no contact record exists for any attendee, create one in your CRM and then manually trigger the sync from the Transcription page.
    </Step>

    <Step title="Confirm the sync">
      Open the Transcription page for the meeting and check the CRM entity selector to confirm a contact has been linked.
    </Step>
  </Steps>

  <Note>
    Internal-only meetings (where all attendees are from your own organization) will not trigger a CRM sync unless your teammates are also present as contacts in the CRM.
  </Note>
</Accordion>

<Accordion title="CRM fields aren't being populated or updated">
  CRM field population has two requirements: a linked deal and Auto-Sync enabled. If either is missing, fields will not update automatically.

  **Check 1 — Is a Deal linked to the meeting?**

  <Steps>
    <Step title="Open the Activity Card or Transcription page">
      Find the meeting on your Home Page or navigate to its Transcription page.
    </Step>

    <Step title="Check the CRM entity selector">
      Look for a linked Deal. If no deal is shown, click the entity selector and link the relevant deal manually.
    </Step>
  </Steps>

  <Note>
    The manual CRM entity selector (used to view or link a Deal, Contact, or Company) is available on Piper's **Pro** plan. If you don't see it, check your plan under **Settings → Billing**.
  </Note>

  **Check 2 — Is Fields Auto-Sync enabled?**

  <Steps>
    <Step title="Go to Settings → Meeting Types">
      Navigate to **Settings**, then select **Meeting Types**.
    </Step>

    <Step title="Check the Auto-Sync toggle">
      Find the Meeting Type that applies to this call. Confirm that **Fields Auto-Sync** is enabled.
    </Step>

    <Step title="Enable Auto-Sync if it is off">
      If Auto-Sync is disabled, CRM fields and tasks are held in **review mode** on the Transcription page. You can approve them individually using the green arrow button, or click **Send All** to push everything at once.
    </Step>
  </Steps>
</Accordion>

<Accordion title="Piper isn't auto-linking a deal to my meeting">
  Piper automatically links a deal to a meeting when it can find a contact attendee who is associated with exactly **one** open deal in your CRM.

  If auto-linking isn't happening, the most likely cause is that the contact is associated with **more than one open deal** — Piper won't guess which one is correct.

  **To link the deal manually:**

  <Steps>
    <Step title="Find the meeting on your Home Page">
      Locate the Activity Card for the meeting.
    </Step>

    <Step title="Use the CRM entity selector">
      Click the deal selector on the Activity Card or on the Transcription page, then choose the correct deal from the list.
    </Step>
  </Steps>

  <Tip>
    If a contact is routinely associated with multiple open deals (e.g., an enterprise account with several active opportunities), consider closing or archiving stale deals in your CRM to allow auto-linking to work reliably.
  </Tip>
</Accordion>

<Accordion title="I only see a few CRM deals in Piper, but my CRM has hundreds">
  Piper doesn't mirror your entire CRM deal list continuously. It only pulls in a deal when:

  * **A linked contact appears on a calendar meeting.** Once a day, Piper checks for CRM deals whose contacts are attendees on a meeting within a few days of that meeting — only those get imported.
  * **The CRM connection was made recently.** When you first connect a CRM, Piper does a one-time backfill of your \~100 most recently updated deals, on top of the meeting-based import above. This only happens once, at connection time.

  A deal with no attendees on your calendar and no recent activity in the CRM at connection time may simply never reach Piper on its own.

  <Tip>
    To pull in a specific deal immediately, search for it by name in any Deal picker — the CRM entity selector on an Activity Card or Transcription page, or the Deal filter on the Deals page. If Piper doesn't already have it, it searches your CRM live and imports the matching deal on the spot.
  </Tip>
</Accordion>

<Accordion title="I see a 'Reconnect with CRM' banner or the integration appears broken">
  CRM integrations — particularly Salesforce — can drop their authentication token due to transient auth errors, session expiry, or a password change on the connected account.

  <Steps>
    <Step title="Go to Settings → Integrations">
      Navigate to **Settings**, then select **Integrations**.
    </Step>

    <Step title="Reconnect your CRM">
      Click **Reconnect** next to your CRM (Salesforce, HubSpot, etc.) and complete the OAuth authorization flow.
    </Step>

    <Step title="Verify the connection">
      After reconnecting, return to a recent Transcription page and confirm that the CRM entity selector loads correctly.
    </Step>
  </Steps>

  <Note>
    Salesforce drops the Piper connection occasionally due to transient authentication errors — this is a known Salesforce OAuth behavior and not a Piper bug. Reconnecting via Settings resolves it immediately.
  </Note>

  <Note>
    Reconnecting a CRM requires the **Owner** or **Admin** role on Piper's **Pro** plan. Standard users see a banner asking them to contact their Team Owner instead of a working **Reconnect** button — if that's you, ask an Admin to complete the steps above.
  </Note>

  **HubSpot-specific requirement:** At least one Piper Admin must also hold **Super Admin** status in HubSpot. If the HubSpot connection is failing, verify that the Piper Admin who connected the integration is a HubSpot Super Admin.
</Accordion>

<Accordion title="Piper seems to be overwriting my existing CRM field values">
  Piper does **not** overwrite existing CRM values. When it updates a field, the formula it uses is:

  > **New CRM value = Current CRM value + Field prompt + Transcription content**

  In other words, Piper appends to or enriches what is already there — it does not replace it.

  If your field values look unexpected, the most likely cause is the prompt configured for that field in your Meeting Type settings.

  <Steps>
    <Step title="Go to Settings → Meeting Types">
      Open the Meeting Type that applies to the call in question.
    </Step>

    <Step title="Review the field prompts">
      Check each CRM field's prompt. Vague or overly broad prompts can result in Piper pulling in more content than you intended. Tighten the prompt to be specific about what information should populate that field.
    </Step>

    <Step title="Save and test">
      Run a test meeting and review the CRM field output to confirm the prompt is producing the result you expect.
    </Step>
  </Steps>
</Accordion>

<Accordion title="Aircall calls aren't appearing in Piper">
  The Aircall integration works at the **phone number** level, not the user account level. Each phone number must be explicitly enabled in the Aircall dashboard before Piper can capture calls made or received on that number.

  <Steps>
    <Step title="Open the Aircall Dashboard">
      Log in to your Aircall account.
    </Step>

    <Step title="Go to Integrations → Piper AI">
      Navigate to **Integrations**, find the **Piper AI** integration, and open its settings.
    </Step>

    <Step title="Add the relevant phone numbers">
      Click **Add Numbers** and enable every phone number whose calls should appear in Piper.
    </Step>

    <Step title="Test with a new call">
      Make or receive a call on one of the enabled numbers and confirm it appears in Piper within a few minutes.
    </Step>
  </Steps>

  <Warning>
    Adding Piper to a user's account does not automatically enable their Aircall numbers. Every number must be individually enabled in the Aircall integration settings.
  </Warning>
</Accordion>

<Accordion title="I'm seeing duplicate notes or logged calls from Aircall and HubSpot together">
  Piper's Aircall integration and its HubSpot Call capture are two independent phone-call sources — each is driven by its own webhook, and Piper does not check whether the other one has already processed the same real-world call.

  If a call reaches Piper through both paths — for example, your numbers are connected through Piper's Aircall integration, and those same calls are also logged into HubSpot with a recording (via Aircall's own native HubSpot connector, or another calling tool) — Piper creates two separate Activities for it, each with its own transcription, notes, and CRM sync. This is expected behavior given how the two integrations work today, not a misconfiguration.

  <Steps>
    <Step title="Identify the second source">
      Check whether your calls are also being logged into HubSpot with a recording by a tool other than Piper — most commonly Aircall's own native HubSpot connector, which is configured separately in the Aircall dashboard, not in Piper.
    </Step>

    <Step title="Keep only one path active">
      Disable whichever path you don't want Piper to process: turn off Piper's Aircall integration if you'd rather rely on HubSpot Call, or remove the other tool's HubSpot call-logging connector if you'd rather keep Piper's Aircall integration as the source of truth.
    </Step>

    <Step title="Contact Piper support if you're unsure">
      If you can't tell which integration is producing the duplicate, Piper support can trace which webhook created each Activity.
    </Step>
  </Steps>

  <Warning>
    Piper does not deduplicate calls across different phone-call sources today. If more than one integration sends Piper the same call, expect a separate Activity — and separate CRM notes — for each one.
  </Warning>
</Accordion>

<Accordion title="Auto-Sync is off — how do I approve pending CRM updates?">
  When Auto-Sync is disabled for a Meeting Type, Piper holds all generated CRM fields and tasks in **review mode** rather than pushing them automatically. This gives you a chance to check the output before it enters your CRM.

  To approve pending updates:

  <Steps>
    <Step title="Open the Transcription page for the meeting">
      Navigate to the relevant meeting and open its Transcription page.
    </Step>

    <Step title="Review the pending fields and tasks">
      Each pending item will be shown with a review indicator.
    </Step>

    <Step title="Approve individually or all at once">
      * Click the **green arrow button** next to an individual field or task to approve it one at a time.
      * Click **Send All** to approve and push everything in one action.
    </Step>
  </Steps>

  <Tip>
    If you want Piper to push CRM updates automatically without manual review, enable **Fields Auto-Sync** in **Settings → Meeting Types** for the relevant Meeting Type.
  </Tip>
</Accordion>