HubSpot Phone Integration with Retell AI: Setup Guide

A HubSpot phone integration with Retell AI is a native connection: you create a HubSpot private app, paste its access token into the Retell dashboard, and one connection gives your agents three things. Contacts sync into Retell so the agent knows who is calling, the agent can read and update HubSpot records during the call, and every call is logged on the contact's activity timeline afterward. No Zapier step or custom middleware is needed for any of it.

There is also a second, separate piece: the Retell AI app in the HubSpot Marketplace, which lets a HubSpot workflow start an outbound call. The two are independent, and many teams run both.

What does the Retell and HubSpot integration do?

The integration moves data in both directions, and each direction is switched on separately. The connection itself only gives the agent its HubSpot tools. Contact sync, write-back of call results and automatic activity logging are opt-in features on top of it, so you can start small and add them as your team trusts the data.

• Contact sync: Direction: HubSpot to Retell, every 5 minutes. Where you turn it on: Set up contact sync.
• Field write-back: Direction: Retell to HubSpot, after each call. Where you turn it on: Sync to HubSpot tab.
• Activity logging: Direction: Retell to the HubSpot timeline. Where you turn it on: Log activities automatically.
• Agent tools: Direction: Live, before, during or after the call. Where you turn it on: Agent Functions or Workflow page.
• Workflow-triggered calls: Direction: HubSpot starts a Retell call. Where you turn it on: HubSpot Marketplace app.

The practical effect for a CX team is that the agent stops asking questions HubSpot already answers. A returning customer is greeted by name, the agent can see their open deal, and your reps find a summary of the call on the record instead of a gap in the history.

Create a HubSpot private app with the right scopes

You need HubSpot Super Admin permissions, because only a super admin can create a private app and grant it scopes. In HubSpot, click Development at the bottom of the left sidebar, select Legacy Apps, click Create legacy app, and choose Private. Some accounts still show this section as Private Apps under Settings → Integrations. Give the app a clear name such as "Retell AI Integration".

On the Scopes tab, click Add new scope and grant what your agents will use:

• crm.objects.contacts.read: import contacts, pass the connection test, look up callers
• crm.schemas.contacts.read: read contact property definitions for mapping and tools
• crm.objects.contacts.write: write back fields, log calls, create notes and tasks
• crm.objects.deals.read and .write: deal tools (optional)
• crm.objects.companies.read and .write: company tools (optional)
• crm.schemas.deals.read and crm.schemas.companies.read: deal and company properties (optional)

Click Create app, confirm with Continue creating, then click Show token and copy the access token. HubSpot authorizes notes, tasks and call engagements through the contact scopes, so there is no separate engagement scope to add.

Grant every scope before you connect. A missing scope does not flag the connection. HubSpot answers with a 403 and that one feature stops working silently, so add the scopes up front (or later under Edit app).

Connect HubSpot in the Retell dashboard

In the Retell dashboard, open Integrations, select the Available tab, find HubSpot and click Connect (or Add Account if a connection already exists). Connecting requires an Admin or Developer role in your Retell workspace. The dialog has two fields:

• Connection name: an alias, prefilled with "HubSpot - API key".
• API Key: the private app access token you just copied.

Retell tests the token immediately by reading a page of contacts. On success, the dialog reports the connection as verified and offers Set up contact sync. On failure it shows HubSpot's own error, which usually means the token is wrong or crm.objects.contacts.read is missing. The full walkthrough, with screenshots, is in the HubSpot connection guide in the Retell docs.

Sync HubSpot contacts so the agent greets callers by name

Contact sync imports your HubSpot contacts into Retell and keeps them current. Click Set up contact sync and map the HubSpot properties you want on the Import contacts tab. Retell pre-fills HubSpot phone to Retell phone_number, and that mapping cannot be removed, because the phone number is how the two systems match a caller to a record.

The first sync is a full scan. After that, Retell polls HubSpot every 5 minutes (as of August 2026) and imports only contacts changed since the last run. Contacts with an empty phone property, or a number that cannot be parsed into E.164 format, are skipped, so clean malformed numbers in HubSpot first.

Synced contact fields become dynamic variables in the agent's prompt. When a call matches a known contact by phone number, the agent starts the call already holding the name, lifecycle stage or any custom property you mapped.

Write call outcomes back to HubSpot after every call

Write-back is where the integration saves your team manual data entry. Two settings do the work, both on the Sync to HubSpot tab.

First, map post-call analysis fields (Retell calls them Post Call Extraction fields) to contact properties. If your extraction pulls a lead_status after each call, map it to a lead status property and choose an update mode: Overwrite for values where the latest answer wins, Fill only if empty for stable data like email, or Accumulate & summarize, which merges old and new text with an LLM at $0.005 per merge (as of August 2026). See Retell pricing for the per-minute rates that apply to the calls themselves.

Second, turn on Log activities automatically. Each call then becomes a Call engagement on the matched contact with status COMPLETED, its duration and direction, and a body carrying the call ID, the from and to numbers, the disconnection reason and the summary. By default Retell only updates contacts that already exist in HubSpot. Turn on Create new contacts in CRM if you want an unknown caller added as a new HubSpot contact after the call.

Let the agent read deals and create tasks during the call

Once HubSpot is connected, its tools appear when you add a function to an agent. They work with or without contact sync. The available tools are Search Contact, Get Contact, Create Contact, Update Contact, List Contact Deals, Get Deal, Update Deal, List Contact Companies, Get Company, Update Company, List Contact Tasks, Create Task, Create Note and Log Call Activity.

Tools can run in three places: during the conversation, as a pre-call function before the agent speaks, or as a post-call function after the call ends. Pre-call and post-call functions live on the agent's Workflow page. A common pattern from the agent workflow docs:

1. A pre-call Search Contact on {{user_number}}, mapping the record ID to hubspot_contact_id.
2. A post-call Log Call Activity on that ID with the body set to {{call_summary}}, gated so it runs only when a summary exists.
3. A parallel post-call Create Task, gated on a followup_needed extraction field, so tasks appear only on calls that earned one.

Inbound calls wait up to 1 minute for pre-call functions before the agent speaks, and post-call functions are capped at 5 minutes in total (as of August 2026). If a HubSpot lookup fails, the call still connects, so write the prompt to read naturally when a field comes back empty.

Trigger outbound calls from HubSpot workflows

The Retell AI app for HubSpot adds a Make a Phone Call action to HubSpot workflows. During installation, copy the Secret Key (Webhook) from Settings → API Keys in Retell into the install form, then paste the webhook URL the form gives you into Settings → Webhooks in Retell.

In HubSpot, go to Automation → Workflows, pick a trigger such as a form submission or a deal stage change, and add a Phone number is known condition. Add the action Retell AI → Make a Phone Call, set From to your Retell agent and number, To to the contact's phone token, and pass optional dynamic variables as JSON. The workflow pauses until the call ends, then you can branch on Call Success, User Sentiment or Call Outcome. This is the usual setup for AI lead qualification on new form fills.

Why aren't calls showing up on the HubSpot timeline?

Activity logging needs three things at once: Log activities automatically enabled, a Retell contact that was imported from this HubSpot connection, and the crm.objects.contacts.write scope. A call from a number that does not match a synced contact is never logged. If the connection itself shows a red Connection error tag, HubSpot rejected the token, usually after a rotation. Paste a current token in the connection's settings and click Reconnect; your mappings and synced contacts are kept.

If your system of record is Salesforce instead, the setup follows the same shape; see how to connect Retell AI to Salesforce. And if callers should keep dialing the number they already know, keep your existing phone number over a SIP trunk before you go live.

You can connect HubSpot, sync a test list and place a call in one sitting. Open the Retell dashboard to start with the free credits and build against your real HubSpot data.