Configure HubSpot

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, 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.
   
5. Connect app to grant permissions and continue.
   
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).

​

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.
  
• 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.
  
• 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.
  
• 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.
  
• 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.
    
  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.
  
• Specify a tag for your HubSpot contacts in CloudTalk and import cases from HubSpot as contact activities.
  
• 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.
  

​

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.

​

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

​

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. If a campaign disposition is mapped to a HubSpot outcome, that value will be used for the call.

​

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.

​

Data Synchronization & Field Mapping

​

New Contact Mapping

* = required field

​

Updating Contact in Hubspot

* = required field

​

Updating Contact in CloudTalk

* = required field

​

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

​

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

​

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 to review your configuration or backend sync adjustments.

​

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

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.

---

Need help or have a question? Just reach out through our Support portal — we’re here for you.