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

# Configure HubSpot

> Configure data exchange between CloudTalk and HubSpot to ensure your data stays up to date.

> [!NOTE]
>
> This article explains how to connect HubSpot with CloudTalk, configure synchronization settings, and understand how data is mapped between the two systems.

**User level:** Admin

***

## Before You Start

* You must be an Admin in CloudTalk.

* You must have permission to install apps in HubSpot.

* The email address you use in CloudTalk must match exactly with the email address in your HubSpot account. If the emails do not match, synchronization will not work correctly.

* CloudTalk agents must have the same email address as their HubSpot user.

* When you first connect HubSpot, CloudTalk imports your deals and tickets along with your contacts. Imported records can't be bulk-removed later.

* Turning off deal or ticket sync later doesn't remove the deals and tickets already imported.

## Connect HubSpot to CloudTalk

1. From your [Dashboard](https://dashboard.cloudtalk.io), navigate to **Settings** > **Integrations**.

2. From the list of integrations, hover over **HubSpot** and select **`+ Add`**.

3. You will be redirected to a HubSpot login to enter your credentials.

4. If you have multiple HubSpot accounts, you will be asked to choose one to integrate with CloudTalk.

   ![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/b34dfb8c386d-screenshot-2025-03-18-at-10-06-03.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=e83bb838a47caa027c5a81d0b6f2ab33)

5. **Connect app** to grant permissions and continue.

   ![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/26afa7a904ab-screenshot-2025-03-18-at-10-32-33.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=a9b12ad21302818a1d832d145ab58afa)

6. After a successful authentication process, you will be redirected back to the CloudTalk dashboard, where you can customize your integration.

7. Click **Save** to enact these changes and activate the integration.

   1. *You can set your integration to Inactive at any time using the toggle at the top.*

Once the integration is set up, all your HubSpot contacts will be synchronized with CloudTalk. When a contact's **owner changes in HubSpot**, CloudTalk updates the contact's **Favorite Agent** accordingly (as long as that user exists as an agent in CloudTalk).

> [!WARNING]
>
> CloudTalk [Workflow Automations](https://help.cloudtalk.io/en/articles/5450779-configuring-workflow-automations.md) work only with the **most recently created HubSpot integration**. Even if you set up multiple HubSpot integrations, changes in HubSpot's authentication structure mean that only the latest integration will function with workflow automations.

## Integration Customization

* **Choose which calls will be logged to HubSpot**. You can define which calls *(inbound, outbound, missed calls and voicemails)* to log into HubSpot. The call will be logged as a HubSpot engagement.

  ![Workflow Settings - Create activities for calls](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/bd298fee242c-image.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=6a90fcdac8d5b965ab359eb7901068ca)

* Select whether CloudTalk should create a call activity in HubSpot **when the call is answered** or **when the call ends**. You can choose when CloudTalk should create a call activity in HubSpot:

  * **Answered**: a call activity will be created in HubSpot as soon as the call is picked up.

  * **Ended**: a call activity will be created only after the call is finished (default behavior).

  This setting gives you flexibility: for example, if your team wants to see calls appear in HubSpot right away or trigger HubSpot workflows as soon as a call starts, use the **Answered** option.

  ![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/6ad88a190b75-screenshot-2025-09-03-at-10-10-34.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=bf2b77eb73eeb21eff4a118bd71e7405)

* **Choose to only link activity from certain numbers** to your HubSpot integration by using the *Connected numbers* section. If this section is left blank, data associated with all company numbers will be synced.

  ![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/f7e343784771-image.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=f394c9266202e7299826e78b900f6f0a)

* Decide whether you want to **log all calls** or **only calls made during business hours**, and where to assign **missed calls.** Customize how **new contacts are created for unassociated numbers**. If **Create new contacts in HubSpot for unassociated call numbers** is off, calls to or from numbers with no matching HubSpot contact are not exported.

  ![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/7256876a6147-image.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=09bc8dd2fddfbb1c10bc7382f7499ffc)

* **Choose how call and SMS activities are associated with HubSpot companies** using the **Strategy for logging calls to HubSpot companies** setting. This controls whether call (and SMS) activities are also logged on the company records linked to the matched contact:

  * **Do not log to a company**: the activity is only logged on the contact, deal, and ticket (same as before this feature).

  * **Log to primary company**: the activity is also logged on the contact's primary company in HubSpot.

  * **Log to all companies**: the activity is logged on every company linked to the contact at the time of export.

    ![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/9ebe3a999a8a-screenshot-2026-06-10-at-14-27-55.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=0fac841d7c9387eda636dc1d7126775b)

  **New integrations** default to *Log to primary company*. **Existing integrations** default to *Do not log to a company*; behavior is unchanged unless you update this setting. The same options are available for SMS under **Workflow Settings for SMS**.

  ⚠️ This setting only applies to activities exported after it is configured. Historical calls and SMS are not retroactively associated with company records.

* Play call recordings and see transcripts directly in HubSpot as **call engagements**.

  ![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/6a881092fe05-image.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=ae97733baa03d7deb8b72254a9f1f844)

* Specify a **tag** for your HubSpot contacts in CloudTalk and **import cases** from HubSpot as contact activities.

  ![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/88cbbeb7dfc2-image.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=ff745de58e40851688bd12d5f4802081)

* Enable **VoiceAgent** call logging and choose which user should be assigned to logged VoiceAgent calls. These calls appear in HubSpot with a "Voice Agent Call" label.

  ![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/124428fd564b-screenshot-2025-07-24-at-10-05-11.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=703b6a6ea421a238013ffc10567c86a9)

### Outcome Mapping

CloudTalk can populate the **HubSpot Activity Outcome** field in three different ways, depending on your configuration.

#### Call Type Disposition

In **Workflow Settings**, you can define a default outcome for each call type using the\
"\<type of call> disposition as" option.

This allows you to assign a specific HubSpot Activity Outcome for:

* Inbound calls

* Outbound calls

* Missed calls

* Voicemails

This setting acts as fallback logic if no other outcome mapping applies.

To set the HubSpot call type, create a call tag with the same name as the HubSpot activity type (not case-sensitive). Calls with that tag get that type. To set both the type and the outcome, agents add two tags: one named like the activity type and one mapped to an outcome.

![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/eb58a58f051a-screenshot-2026-02-13-at-11-18-39.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=2135b56cf1268cfb22eb5a05a075f030)

#### Tag-Based Outcome Mapping

Within the **Outcome Mapping** section, you can map CloudTalk call tags to specific HubSpot Activity Outcomes.

When a mapped tag is applied to a call, the corresponding HubSpot outcome will be used.

If multiple mapped tags are applied to the same call, the first one listed in the Outcome Mapping table determines the outcome. You can drag and drop outcomes to reorder them.

You can also configure a default outcome that will be used if no mapped tag is present.

New tags aren't mapped automatically, even if they have the same name as a tag you've already mapped. Map each new tag in Outcome Mapping, or reuse existing tags instead of creating duplicates.

Each mapping row uses one CloudTalk call tag, and you can map several tags to the same HubSpot outcome. When every call tag is already mapped, you can't add another row. To map more, first [create a new call tag](https://help.cloudtalk.io/en/articles/5854602-call-tags.md#h_aafd08a5dd).

**Calls that reach voicemail.** A manual or click-to-call call that reaches voicemail counts as answered, so HubSpot logs it as **Connected**. To log these calls with another outcome, such as **No answer** or **Left voicemail**, create a call tag (for example, "Voicemail"), map it to that outcome here, and have agents add the tag to these calls.

![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/74b9398ecc98-screenshot-2026-02-13-at-11-32-01.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=953806b2917878add84411fe32e51471)

#### Campaign Disposition Mapping

When using CloudTalk Campaign Dialer, you can map campaign dispositions to HubSpot Activity Outcomes using the **Integration Mapping** column in **[Disposition Settings](https://help.cloudtalk.io/en/articles/9562215-using-hubspot-with-campaign-dialers.md#:~:text=PM%20each%20day.-,Disposition%20Mapping%20to%20HubSpot%20Outcomes,-%E2%9A%A0%EF%B8%8F%20Important%3A)**.

If a campaign disposition is mapped to a HubSpot outcome, that value will be used for the call.

![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/72b6ade73182-screenshot-2026-02-13-at-11-24-01.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=c8828e4b14a2abbfa0c9d14b446711ec)

#### Outcome Priority Logic

If multiple configurations apply to the same call, the HubSpot Activity Outcome is determined in the following order of priority:

1. **Campaign Disposition Mapping** (highest priority)

2. **Tag-Based Outcome Mapping**

3. **Workflow Call Type Setting** (fallback)

#### Where HubSpot Call Outcomes Come From

CloudTalk pulls HubSpot call outcomes from HubSpot's internal Calling settings. These outcomes come from the system field called `hs_call_disposition`, which HubSpot uses to store call and meeting outcomes.

Only the outcomes created in HubSpot's Calling Outcome settings can appear in CloudTalk. Creating "Call Outcomes" as a custom CRM property will not work, since CloudTalk does not read outcomes from custom properties.

HubSpot allows customers to manage call outcomes directly in the Calling settings. Custom call outcomes must be created in the HubSpot UI.

For more information, see [HubSpot's guide on creating custom call outcomes](https://knowledge.hubspot.com/calling/create-custom-call-and-meeting-outcomes).

> [!NOTE]
>
> **Calling from HubSpot**
>
> Follow [HubSpot's CTI guide](https://knowledge.hubspot.com/calling/integrate-a-third-party-calling-provider-with-hubspot) to set up CloudTalk as your primary phone in HubSpot, and check out our guides for [using the HubSpot CTI](https://help.cloudtalk.io/en/articles/5368689-cloudtalk-phone-in-hubspot.md) and [quick fixes](https://help.cloudtalk.io/en/articles/8272721-hubspot-quick-fixes.md).

## Data Synchronization & Field Mapping

### New Contact Mapping

\* = required field

| **CloudTalk Contact** | **Sync Direction** | **HubSpot Contact** |
| - | - | - |
| Full name\* (1st name is the 1st word only) | ⬅➡ | First name\* & Last name\* |
| Phone number(s)\* (only 1st & 2nd number) | ⬅➡ | Phone number (primary number & mobile number) |
| Email\* (only 1st email address) | ⬅➡ | Email\* (only primary email) |
| Company | ➡ | Company name (not a linked HubSpot company) |
| Address | ➡ | Street address |
| City | ➡ | City |
| Zip | ➡ | Postal code |
| State | ➡ | State/region |
| Favorite agent | ⬅ | Contact owner (only existing CloudTalk Agents email addresses) |
| Tags (contact-level) | 🚫 | Not synced as contact properties |
| Custom fields | 🚫 | Not synced |

### Updating Contact in Hubspot

\* = required field

| CloudTalk Contact | Updated | HubSpot Contact |
| - | - | - |
| Full name\* (1st name is the 1st word only) | ⬅ | First name\* & Last name\* |
| Phone\* (adds another number, keeps old numbers) | ⬅ | Phone number (primary & mobile numbers) |
| Email (adds another email address, keeps old email addresses) | ⬅ | Email\* (only primary email address) |
| Company | 🚫 | Company name or associated Company |
| Address | 🚫 | Street address |
| City | 🚫 | City |
| Zip | 🚫 | Postal code |
| State | 🚫 | State/region |
| Favorite agent | ⬅ | Contact owner |
| Tags (contact-level) | 🚫 | Not synced |
| Custom fields | 🚫 | Not synced |

### Updating Contact in CloudTalk

\* = required field

| **CloudTalk Contact** | **Updated** | **HubSpot Contact** |
| - | - | - |
| Full name\* (1st name is the 1st word only) | ➡ | First name\* & Last name\* |
| Phone\* (editing 1st option updates primary number) | ➡ | Phone number (primary & mobile numbers) |
| Email (editing 1st option updates primary email address) | ➡ | Email\* (only primary email address) |
| Company | ➡ | Company (not a linked HubSpot company) |
| Address | ➡ | Street address |
| City | ➡ | City |
| Zip | ➡ | Postal code |
| State | ➡ | State/region |
| Favorite agent | 🚫 | Contact owner |
| Tags (contact-level) | 🚫 | Not synced |
| Custom fields | 🚫 | Not synced |

### Stop CloudTalk from Sending Contacts to HubSpot

There's no toggle for this in settings, but our engineering team can switch it off for you on the backend. [Contact Support](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884) and tell us which of these you want to turn off. You can turn off one or both:

* **Contact updates:** CloudTalk stops changing existing contacts in HubSpot.
* **Contact creation:** CloudTalk stops creating new contacts in HubSpot.

This covers every way a contact can be created or changed in CloudTalk: in the Dashboard or app, through the API or another integration, or automatically after a call or SMS.

Contacts still sync **from HubSpot to CloudTalk** as before, so your HubSpot contacts keep showing up in CloudTalk.

> [!WARNING]
>
> ⚠️ If a CloudTalk contact has no name and is matched to a HubSpot contact by phone number, a sync can clear the name in HubSpot. To prevent this, make sure your CloudTalk contacts have names saved, or contact [Support](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884) to turn off contact updates from CloudTalk to HubSpot.

### Preventing Custom Field Data Loss with HubSpot Sync & Automations

When **HubSpot inbound contact sync** is enabled, using CloudTalk Workflow Automations to update contact properties can inadvertently clear your CloudTalk-only custom fields.

#### **How the Overwrite Occurs**

1. A **[Workflow Automation](https://help.cloudtalk.io/en/articles/10568412-workflow-automations-guide.md)** (or external tool like Zapier/n8n) edits a contact in CloudTalk.

2. CloudTalk emits a `contact edited` event.

3. The HubSpot integration detects the event and forces a contact re-sync using **HubSpot's version** of the contact.

4. Because HubSpot does not track CloudTalk-only custom fields, it overwrites those fields in CloudTalk with empty values.

> [!WARNING]
>
> *Note: Manually editing a contact in CloudTalk does not trigger this sync loop.*

#### **Recommended Actions**

* **Audit Automations:** Remove unnecessary contact-edit actions from your CloudTalk Workflow Automations, or adjust triggers to prevent contact updates.

* **Review External Tools:** Be cautious when using Zapier or n8n to populate CloudTalk-only fields if a CloudTalk automation immediately edits the same contact afterwards.

* **Contact Support:** [Reach out to CloudTalk Support](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884) to review your configuration or backend sync adjustments.

> [!NOTE]
>
> ⚠️ This behavior is linked to a known engineering issue. If custom fields are disappearing at scale across your account, **pause the affected automations immediately** and contact Support to prevent further data loss.

## Disconnect HubSpot Integration

In the event that you decide to stop using HubSpot with CloudTalk, you can follow these steps to disconnect the integration.

1. Log in to your [Dashboard](https://dashboard.cloudtalk.io/) and go to **Settings > Integrations** from the left menu.

2. This page displays your current integrations. Next to the HubSpot integration, select **`Change`**.

3. Scroll down and select **Delete Integration**.

4. To confirm, type `DELETE` and select **Delete.**

   ![](https://mintcdn.com/cloudtalk/NaLCtq06pFIW2ogE/images/help-center/articles/3206271/7b284460e9bb-image.png?fit=max\&auto=format\&n=NaLCtq06pFIW2ogE\&q=85\&s=6916cfdcd3b00a75575630bc738c3efc)

Once you have completed these steps, the integration will be deleted from your CloudTalk dashboard. There are additional steps to follow to [remove CloudTalk within HubSpot](https://knowledge.hubspot.com/integrations/connect-apps-to-hubspot#uninstall-an-app).

> [!WARNING]
>
> **Warning:** Disconnecting and uninstalling CloudTalk will prevent information such as call data from being shared to and from HubSpot, which will further affect any linked HubSpot accounts and their data.

***

*Need help or have a question?* Just reach out through our [Support portal](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884) — we're here for you.


## Related topics

- [Configure HubSpot Help Desk](https://help.cloudtalk.io/en/articles/16900799-configure-hubspot-help-desk.md)
- [Using CloudTalk with HubSpot](https://help.cloudtalk.io/en/articles/14136029-using-cloudtalk-with-hubspot.md)
- [HubSpot SMS Workflows](https://help.cloudtalk.io/en/articles/6118552-hubspot-sms-workflows.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.