How to set up the HubSpot integration

The HubSpot integration automatically syncs contacts and companies between Nuvia and your HubSpot account. This keeps your data up to date on both platforms, removes the need for manual syncing, and creates a continuous feedback loop between inbound and outbound.

Available on: Platform > Integrations > HubSpot

Who can do it: Admin

---

What you need before you start

• Owner or Admin access to your Nuvia account

• An active HubSpot account (any plan)

• Permission to connect third-party apps to your HubSpot account

• Clarity about which fields you want to sync between the platforms

• Your default country calling code (the code that identifies the country) defined

---

Connect your HubSpot account

1. Go to Settings > Integrations

2. Find HubSpot in the list and click to open the panel

3. Click Integrate and then Add account

4. Log in to HubSpot and grant the requested permissions

5. You'll be redirected back to Nuvia with the Connected status

---

Set up field mapping

Field mapping determines which information is synced between Nuvia and HubSpot. Nuvia doesn't come with preconfigured mappings; they're all defined manually.

1. On the HubSpot integration page, find your account and click Configure

2. Click Fields

3. Click add mapping

4. Select the Nuvia field (right) and the HubSpot property (left) to link them

5. Click Save mappings

---

Set up funnel stage mapping

Aligns sales stages between the platforms so that pipeline moves are reflected automatically.

1. On the HubSpot integration page, click the Funnels tab

2. Define the template used to name the deals created automatically in HubSpot.

3. For each Nuvia funnel stage, select the matching deal stage in HubSpot

4. Click Save mapping

---

Set the default country code

The default country code fills in the country code for phone numbers that come from HubSpot without it, so the contact is created correctly in Nuvia.

1. Open the Advanced tab

2. Under Phone Settings, select the country code in the selector (e.g., +55 - Brasil)

The setting is saved automatically when you select it — there's no Save button.

How the rule works:

• It's only applied when the number has 11 digits or fewer and doesn't already start with that country code

• Numbers that already arrive in international format (with +) aren't changed

• For Brazil, an 8-digit number starting with 6, 7, 8, or 9 automatically gets the ninth digit

• Numbers with fewer than 8 digits are discarded and the contact isn't created

• The None (detect automatically) option makes Nuvia try to identify the country from the first digits, which can be wrong

---

Advanced tab settings

Besides the default country code, the Advanced tab brings together the account's sync rules.

---

Automatic contact creation

In the Advanced tab, find Automatic contact creation and click the button to turn it on. When on, every contact who starts a conversation is created in HubSpot – or linked, if a record with the same phone or email already exists.

• On: makes sure no conversation is left without a matching contact in HubSpot

• Off: control becomes individual per funnel stage (only the stages set up to create a contact in HubSpot will trigger creation)

---

Update the owner when the Contact/Deal is updated in HubSpot

Toggle in the Advanced tab. When on, changes to the Contact Owner or Deal Owner made in HubSpot are automatically reflected in the agent linked to the contact's open conversation in Nuvia – keeping the same agent or AI replying, without transferring the conversation.

How to set it up:

1. In the Users tab, set the Sync source (Contact Owner or Deal Owner) and map HubSpot users to Nuvia users

2. In the Advanced tab, turn on the Update the owner when the Contact/Deal is updated in HubSpot toggle

Behavior:

• Nuvia receives the HubSpot webhook with the new owner

• It identifies the matching Nuvia user using the mapping in the Users tab

• It finds the contact's most recent open conversation and updates the linked agent

• The agent or human who was replying keeps replying (the conversation isn't transferred)

---

Check the sync history

The sync history shows a complete record of all syncs, updates, errors, and conflicts.

1. On the HubSpot integration page, click the History tab

2. Review the records by date/time, type, action, and status

3. Click an error to see details and guidance on how to fix it

Two new event types in the filter

The history's event type filter has two new options:

• Owner assigned → Nuvia set the owner of the contact or deal in HubSpot. When the assignment fails, the event appears as Owner assignment failed

• Transcript sent → Nuvia sent the conversation transcript to HubSpot. When sending fails, the event appears as Transcript sending failed

See the data behind each event

When you click an event in the history, the detail panel opens with up to three blocks of data; which ones appear depends on the event's direction.

• Mapped fields (both directions) → only the fields you mapped in Fields, with the value that traveled in that event. A field that wasn't sent is marked (not sent)

• Fields received from HubSpot (only when the event came from HubSpot) → everything HubSpot returned in that event, not just what you mapped, including native fields like email, phone, and company. Each row shows the property's friendly name, the technical name below it (e.g., contacts.email), and the (mapped) tag when that property is in your mapping

• Nuvia data at send time (only when the event left Nuvia) → the state of the record in Nuvia at the moment of sending. This is the block that explains why a field went out empty or with a different value than expected

Two useful details when reading the received fields:

• One event carries more than one entity. A deal event carries the properties of the deal and of the associated contact. The technical name below each row tells you which entity each value comes from (deals., contacts., leads.)

• Dropdown fields show the label, not the code. If the HubSpot property is a selection, Nuvia replaces the internal value with the text you see in HubSpot

Find an event by contact, conversation, or HubSpot IDs

The history search field no longer searches only by name and phone. Now the text you type is also compared with the identifiers saved in each event:

• Nuvia contact ID → brings all events for that contact, including deal and lead events associated with it

• Nuvia conversation ID → brings the events linked to that conversation

• HubSpot contact ID → brings the events for that contact, even when the event's main object was a deal or a lead

• HubSpot deal ID and HubSpot lead ID → bring the events for that deal or lead

• The contact's name or phone still works as before

The field's placeholder text changed to “Search by name, phone, conversation, or ID…” to reflect this.

Filter only failures

The event type selector now also lists failure events, which previously didn't appear in the list and so couldn't be isolated:

• Contact sync failed

• Deal creation failed

• Deal stage update failed

• Field sync failed

• Lead creation failed

• Owner assignment failed

• Transcript sending failed

Use this filter when you only want to see what went wrong, without scrolling through the success records.

Share an already filtered history

History filters are now saved in the page address. This means:

• When you apply search, event type, direction, status, or object type, the address in the browser updates on its own

• You can copy the address and send it to someone else, and they'll open exactly the same filtered list

• Coming back to the page through a saved address restores the filters that were applied

• The address also stores which HubSpot settings tab you're on and which account is selected. If the company has a single account connected, the address works even without specifying the account

---

Go from the contact straight to the sync history

In the contact's fields tab, both in the conversation panel in the Inbox and in the contact panel, the HubSpot section now has a clock with an arrow icon (history) next to the IDs.

Clicking it opens, in a new tab, the HubSpot History already filtered by that contact. It's the shortest way to answer “what did Nuvia send and receive about this contact?” without going through Settings or building the filter by hand.

• When the icon appears: only when the contact has some link to HubSpot (contact, deal, or lead ID) and your role has permission to view settings

• Where it appears: once per contact, on the Contact ID when it exists; otherwise, on the Deal or Lead ID

• What the filter brings: all events for the contact, without separating by object type; associated deals and leads are included

---

Open a contact or deal directly in HubSpot from a conversation

With the integration active, an external link icon appears in the contact's fields tab inside the Conversations module. This lets you open the matching contact or deal directly in the HubSpot interface, without leaving Nuvia and searching manually.

How to use it

1. Open a conversation in the Conversations module

2. Click View details below the user's name

3. In the right side panel, click the Data tab

4. Find the HubSpot section at the bottom of the screen – it appears when the contact is linked to a record in HubSpot

5. Next to the Contact ID or Deal ID, click the external link icon (a square with an arrow)

6. The contact profile or deal opens directly in HubSpot in a new tab

---

Frequently asked questions