1. [Help](https://nuvia.ai/en/docs) 2. [Integrations](https://nuvia.ai/en/docs/colecoes/19378002-integrations) 3. [HubSpot](https://nuvia.ai/en/docs/colecoes/19431232-hubspot) # How to set up the HubSpot integration Sync HubSpot with Nuvia: contacts, companies, and deals in real time, with field mapping, funnel stages, and configurable two-way rules. Available on Platform > Integrations > HubSpot Who can do it Admin Updated on November 3, 2026 [HubSpot](https://nuvia.ai/en/docs/colecoes/19431232-hubspot) 1. [How to set up the HubSpot integration](https://nuvia.ai/en/docs/artigos/14501908-how-to-set-up-the-hubspot-integration) 2. [How to sync contacts and deals between Nuvia and HubSpot](https://nuvia.ai/en/docs/artigos/14590403-how-to-sync-contacts-deals-nuvia-hubspot) 3. [What Nuvia syncs with HubSpot and when](https://nuvia.ai/en/docs/artigos/16473526-what-nuvia-syncs-with-hubspot-and-when) 4. [How to map fields between Nuvia and HubSpot](https://nuvia.ai/en/docs/artigos/16474177-how-to-map-fields-between-nuvia-and-hubspot) 5. [Troubleshooting the HubSpot integration](https://nuvia.ai/en/docs/artigos/16474434-troubleshooting-hubspot-integration) 6. [How to send Nuvia WhatsApp templates straight from a HubSpot workflow](https://nuvia.ai/en/docs/artigos/15879535-send-nuvia-whatsapp-templates-from-hubspot-workflow) 7. [How to enroll leads/contacts in Nuvia campaigns directly from a HubSpot workflow](https://nuvia.ai/en/docs/artigos/15879734-enroll-contacts-nuvia-campaigns-from-hubspot-workflow) 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 Important the connection requires owner or admin permissions on your HubSpot account. Important connecting the account does **not** import the database that already exists in HubSpot. From the moment of connection, Nuvia only syncs what changes going forward. To bring in contacts that already exist in HubSpot, use **Lists > Import members**. ### 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** Tip custom fields are fully supported. Any HubSpot property (including custom properties) can be mapped to any Nuvia custom field. Critical **dropdown** and **multiple choice** fields require the option text in Nuvia to be identical to HubSpot's — including capitalization, accents, and spaces. Any mismatch makes HubSpot reject **the entire record**, and none of the other fields for that contact are saved, with no warning on screen. Before mapping selection fields, read [How to map fields between Nuvia and HubSpot](https://nuvia.ai/en/docs/artigos/16474177-how-to-map-fields-between-nuvia-and-hubspot). ### 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** Note field mapping and stage mapping are independent mechanisms. Mapping a field doesn't move a stage, and mapping a stage doesn't sync a field. Details in [What Nuvia syncs with HubSpot and when](https://nuvia.ai/en/docs/artigos/16473526-what-nuvia-syncs-with-hubspot-and-when). ### 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 Important the default country code **only works on incoming data**. It **doesn't change** the phone number Nuvia sends to HubSpot — outgoing, the country code and number go exactly as saved on the Nuvia contact. If phone numbers arrive wrong in HubSpot, fix them in the contact record, not in this setting. ### Advanced tab settings Besides the default country code, the **Advanced** tab brings together the account's sync rules. SettingWhat it does **Update fields** The **Sync fields** button reloads HubSpot properties, makes new ones available for mapping, and removes mappings for properties that no longer exist **Automatic contact creation** Creates or links the contact in HubSpot when a conversation starts **Update the owner when the Contact/Deal is updated in HubSpot** Reflects in Nuvia an owner change made in HubSpot **Check properties before the agent** Fetches the contact's properties from HubSpot in real time before each agent reply. Adds one lookup per conversation (API cost and limit) and is off by default **Send transcript to HubSpot after it's resolved** Sends the content of the resolved conversation as a communication record associated with the contact. Works for WhatsApp and LinkedIn **Webhook event sources** Lets you discard events coming from certain HubSpot sources (manual edit, form, automation, workflow, integrations and API, import, migration) Important only turn off an **event source** in an emergency. Events from that source are discarded on arrival and can't be recovered later. ### 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) Tip this setting takes priority over per-stage control. If it's on, it creates the contact in any new conversation, regardless of the stage. ### 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) Important the toggle is disabled while the **Sync source** is set to **Disabled**. Set up user mappings in the **Users** tab before turning it on. Tip if the new HubSpot owner has no mapping to a Nuvia user, or if the contact has no open conversation when the webhook arrives, Nuvia silently ignores the event and changes nothing. ### 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 Tip logs are kept for **7 days** and there's no automatic failure alert. Check the History regularly, especially after changing fields or stages. For a step-by-step diagnosis, see [Troubleshooting the HubSpot integration](https://nuvia.ai/en/docs/artigos/16474434-troubleshooting-hubspot-integration). #### 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 Note the field blocks only load when you open the event — that's why the panel shows **“Loading the fields for this event…”** for a moment. If loading fails, the warning **“Couldn't load the fields for this event”** appears with a **Try again** button: it's a loading failure and doesn't mean the event has no data. #### 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. Good to know identifiers are saved in the event itself at the moment it happens. Older events, recorded before this change, may not have all IDs filled in; in those cases, searching by name or phone is still the way to go. #### 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 Tip if the history icon doesn't appear for you, check with the admin whether your role has access to **Platform > Integrations**. Without that permission, the HubSpot panel is inaccessible and the shortcut is hidden on purpose. ### 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 Tip the external link icon only appears when your HubSpot account is connected and the portal ID is set up correctly. If the icon doesn't appear, check that the integration has the **Connected** status in **Platform > Integrations > HubSpot**. ## Frequently asked questions ## Frequently asked questions **How often does Nuvia sync data with HubSpot?** Sync is real-time and event-driven. When something changes in HubSpot, a webhook notifies Nuvia instantly. There's no configurable interval. Connecting the account, however, doesn't do an initial load: only what changes from then on is synced. **If I delete a contact in Nuvia, is it deleted in HubSpot?** No. Deletions aren't propagated in either direction. If you need to remove data from both platforms (e.g., an LGPD request), you must delete it manually in each one. **Can I sync only some fields, not all?** Yes. In the Fields tab, you choose exactly which fields to sync. Unmapped fields aren't synced. **I set the default country code and phone numbers still go out wrong to HubSpot. Why?** Because the default country code only acts on numbers that **come from HubSpot**. Outgoing, Nuvia sends the country code and number exactly as saved on the contact. The fix is in the contact record in Nuvia. **Does the external link to HubSpot inside the conversation appear for all users?** Yes, the external link icon appears for any user with access to the conversation, as long as the HubSpot integration is active and the contact is linked to a record in HubSpot. The **sync history** icon is different: it requires permission to view settings, because it takes you inside the Integrations panel. **I searched by contact ID in the history and nothing came up. Why?** Identifiers are saved in the event at the moment it happens. Events recorded before this change may not have the ID filled in; try the contact's name or phone. Also remember that logs are kept for only 7 days. **If I change a contact's owner in HubSpot, does the agent in Nuvia change automatically?** Only if the **Update the owner when the Contact/Deal is updated in HubSpot** toggle is on in the **Advanced** tab, and the **Sync source** is set up in the **Users** tab. When it's on, Nuvia updates the agent of the contact's open conversation, keeping the same agent or AI replying (without transferring the conversation). **Does owner sync affect conversations that are already closed?** No. Nuvia only updates conversations with the **Open** status when the webhook arrives. Closed or resolved conversations aren't changed, even if the HubSpot owner changes. **What if I have multiple HubSpot accounts?** Currently, Nuvia supports a single HubSpot account per workspace. If you need to connect multiple accounts, you'll need to create separate Nuvia workspaces. **Does the HubSpot integration work with the Campaigns module?** Partially. HubSpot events can trigger campaigns automatically in Nuvia via webhooks. Nuvia doesn't send campaign performance data back to HubSpot; that data is only visible in Nuvia's Dashboards. **Can I export the sync history for auditing?** No. The history is only available for viewing in the interface, with filters by type, direction, status, and object, and also through the page address, which you can copy and share already filtered. Remember that logs are kept for only 7 days. [NextHow to sync contacts and deals between Nuvia and HubSpot](https://nuvia.ai/en/docs/artigos/14590403-how-to-sync-contacts-deals-nuvia-hubspot) Was this article helpful? ## Related articles - [How to send Nuvia WhatsApp templates straight from a HubSpot workflow](https://nuvia.ai/en/docs/artigos/15879535-send-nuvia-whatsapp-templates-from-hubspot-workflow) - [What Nuvia syncs with HubSpot and when](https://nuvia.ai/en/docs/artigos/16473526-what-nuvia-syncs-with-hubspot-and-when) - [How to map fields between Nuvia and HubSpot](https://nuvia.ai/en/docs/artigos/16474177-how-to-map-fields-between-nuvia-and-hubspot) - [Troubleshooting the HubSpot integration](https://nuvia.ai/en/docs/artigos/16474434-troubleshooting-hubspot-integration) [HubSpot](https://nuvia.ai/en/docs/colecoes/19431232-hubspot) 1. [How to set up the HubSpot integration](https://nuvia.ai/en/docs/artigos/14501908-how-to-set-up-the-hubspot-integration) 2. [How to sync contacts and deals between Nuvia and HubSpot](https://nuvia.ai/en/docs/artigos/14590403-how-to-sync-contacts-deals-nuvia-hubspot) 3. [What Nuvia syncs with HubSpot and when](https://nuvia.ai/en/docs/artigos/16473526-what-nuvia-syncs-with-hubspot-and-when) 4. [How to map fields between Nuvia and HubSpot](https://nuvia.ai/en/docs/artigos/16474177-how-to-map-fields-between-nuvia-and-hubspot) 5. [Troubleshooting the HubSpot integration](https://nuvia.ai/en/docs/artigos/16474434-troubleshooting-hubspot-integration) 6. [How to send Nuvia WhatsApp templates straight from a HubSpot workflow](https://nuvia.ai/en/docs/artigos/15879535-send-nuvia-whatsapp-templates-from-hubspot-workflow) 7. [How to enroll leads/contacts in Nuvia campaigns directly from a HubSpot workflow](https://nuvia.ai/en/docs/artigos/15879734-enroll-contacts-nuvia-campaigns-from-hubspot-workflow) ## Still need help? Customers reach support through the chat inside the platform. Not a customer yet? Talk to our team. [Talk to support in the platform](https://app.nuvia.ai) [I'm not a customer yet](https://nuvia.ai/en/contact) --- Source: https://nuvia.ai/en/docs/artigos/14501908-how-to-set-up-the-hubspot-integration