# Integrazione HubSpot: l'agente Nodale sincronizza i lead Bastien Izzo, CEO · Pubblicato il 4 novembre 2026 > **In breve.** Collega HubSpot dalla pagina delle integrazioni del tuo workspace Nodale. Dopo ogni conversazione, Nodale trova o crea il contatto e la sua azienda, compila le proprietà HubSpot che hai mappato nella direzione di sincronizzazione scelta e aggiunge una nota al contatto, alla sua azienda e alle sue trattative aperte. Nodale è un agente AI che trasforma l'inbound in lead caldi: i visitatori dei siti B2B ottengono risposte e una demo dal vivo, 24/7 e in oltre 50 lingue, e condividono intenzione, caso d'uso e budget, così le aziende convertono una parte maggiore del traffico che già pagano. Questa pagina è per l'admin di un workspace Nodale che collega HubSpot. Spiega cosa Nodale chiede a HubSpot, cosa vi scrive e cosa rilegge. ## Installa l'integrazione Devi essere **admin del tuo workspace Nodale** e un utente HubSpot autorizzato a installare app nel tuo portale. Gli altri membri del workspace vedono il collegamento, ma non possono modificarlo. 1. In Nodale, apri **Settings**, poi **Workspace**, poi **Integrations**, e scegli la scheda **HubSpot**. 2. Clicca su **Connect HubSpot**. HubSpot apre la sua pagina di consenso. 3. Scegli il portale da collegare, leggi gli scope (elencati sotto) e accettali. 4. HubSpot ti riporta su Nodale, che mostra: «HubSpot is connected. Your portal is shown below.» La scheda del collegamento mostra poi il portale, la data del collegamento e l'ultima sincronizzazione. Un workspace Nodale collega un solo portale HubSpot. Al momento del collegamento, Nodale aggiunge al tuo portale una proprietà azienda nascosta, **Nodale record ID** (`nodale_external_id`), in un gruppo di proprietà chiamato **Nodale**. Serve a Nodale per ritrovare le aziende che ha creato. ## Gli scope richiesti da Nodale HubSpot mostra questi scope nella sua pagina di consenso. Sono tutti obbligatori. | Scope | Cosa ne fa Nodale | |---|---| | `oauth` | Identifica il portale che hai collegato. | | `crm.objects.contacts.read` | Trova un contatto tramite l'email e legge le proprietà che hai mappato. | | `crm.objects.contacts.write` | Crea e aggiorna i contatti, e associa un contatto alla sua azienda. | | `crm.objects.companies.read` | Trova un'azienda tramite il dominio o tramite la sua associazione con il contatto, e ne legge le proprietà mappate. | | `crm.objects.companies.write` | Crea e aggiorna le aziende. | | `crm.objects.deals.read` | Elenca le tue pipeline di trattative e trova le trattative aperte del contatto, per allegarvi la nota. | | `crm.objects.deals.write` | Richiesto insieme agli scope CRM. Nodale non crea né modifica alcuna trattativa. | | `crm.schemas.contacts.read` | Elenca le proprietà contatto che puoi mappare. | | `crm.schemas.contacts.write` | Crea una proprietà contatto quando la richiedi da Nodale. | | `crm.schemas.companies.read` | Elenca le proprietà azienda che puoi mappare. | | `crm.schemas.companies.write` | Crea una proprietà azienda quando la richiedi, e la proprietà Nodale record ID. | | `crm.schemas.deals.read` | Richiesto insieme agli scope CRM. Nodale non mappa alcuna proprietà delle trattative. | | `crm.schemas.deals.write` | Richiesto insieme agli scope CRM. Nodale non crea alcuna proprietà delle trattative. | | `scheduler.meetings.meeting-link.read` | Legge i tuoi link per le riunioni HubSpot, perché l'agente possa prenotarvi riunioni (vedi sotto). | ## Contatti e aziende ### Quando Nodale legge e scrive in HubSpot - **Appena il visitatore fornisce un'email**, Nodale legge il contatto e la sua azienda in HubSpot, così l'agente sa cosa il tuo CRM conosce già di lui. La lettura non scrive mai nulla in HubSpot. - **Dopo ogni conversazione**, quando Nodale ha scritto il suo riepilogo, invia il lead a HubSpot. Un lead viene inviato quando ha un'email, che sia qualificato o no. - I lead precedenti al collegamento non vengono inviati. ### Come Nodale trova il contatto e l'azienda - **Il contatto**: quello che Nodale ha già associato, altrimenti quello con la stessa **email**, altrimenti Nodale lo crea. Un contatto archiviato non viene toccato. - **L'azienda**: l'azienda principale del contatto in HubSpot, altrimenti quella che Nodale ha già associato, altrimenti l'azienda con lo stesso **dominio**, altrimenti Nodale la crea con quel dominio e vi associa il contatto. Per un indirizzo email personale (Gmail, per esempio) non viene cercata alcuna azienda. ### Mappa i campi Apri la scheda **Mapping** della pagina HubSpot. Ogni riga invia un campo Nodale a una proprietà HubSpot. ![La scheda Mapping dell'integrazione HubSpot in Nodale](https://nodale.ai/assets/integrations/hubspot/mapping.webp) - **Always sent here**: l'email va nella proprietà `email` del contatto, il dominio dell'azienda nella proprietà `domain` dell'azienda. Compilano la proprietà quando è vuota. - **Identity**: nome, cognome, ruolo. - **Context**: UTM source, UTM medium, UTM campaign e sito di provenienza, dalla prima visita del lead. - **Qualification**: gli elementi del framework di qualificazione del tuo agente. - **Custom**: i campi personalizzati del tuo workspace, sul contatto o sull'azienda. La prima volta, Nodale propone una mappatura: i campi di identità e di contesto abbinati alle proprietà HubSpot con lo stesso nome. Convalidala, oppure parti da zero. Le modifiche restano in bozza finché non clicchi su **Validate**. Rimuovere una mappatura non elimina alcun campo Nodale né alcuna proprietà HubSpot. Un campo in errore non viene inviato finché non lo correggi; tutto il resto continua a sincronizzarsi. **Creare una proprietà HubSpot.** Per un campo senza proprietà, scegli **Create a HubSpot property**: alla convalida, Nodale la aggiunge a HubSpot nel gruppo **Nodale** (con nome `nodale_...`) e vi invia il campo. **Importare proprietà HubSpot.** **Add HubSpot properties to Nodale** trasforma le proprietà HubSpot che selezioni in campi Nodale, mappati su di esse. Un menu a discesa diventa un campo a scelta, una casella di controllo un campo sì/no, tutto il resto un campo di testo. **Abbinare i valori.** Un campo a scelta inviato a un menu a discesa richiede che ciascuno dei suoi valori sia abbinato a un'opzione HubSpot. Non viene inviato finché ogni valore non ne ha una. ### Scegli la direzione di sincronizzazione Ogni campo mappato ha una direzione di sincronizzazione. Quella predefinita è **Bi-sync on create, HubSpot priority on update**. Un valore Nodale vuoto non svuota mai HubSpot. ![Il menu della direzione di sincronizzazione di un campo mappato in Nodale](https://nodale.ai/assets/integrations/hubspot/sync-direction.webp) | Direzione di sincronizzazione | Primo invio del lead | Invii successivi | Entrambi hanno un valore | |---|---|---|---| | **Bi-sync** | Ciascun lato compila il valore vuoto dell'altro; un valore HubSpot già compilato prevale | Si propaga il lato modificato dall'ultima sincronizzazione | Primo invio: prevale HubSpot. Poi il lato modificato dall'ultima sincronizzazione; HubSpot se sono cambiati entrambi | | **Bi-sync on create, HubSpot priority on update** (predefinita) | Ciascun lato compila il valore vuoto dell'altro | Prevale HubSpot se ha un valore, altrimenti lo compila Nodale | Al primo invio ciascuno mantiene il proprio, poi prevale HubSpot | | **HubSpot priority** | Il valore HubSpot torna in Nodale; Nodale non scrive mai | Come sopra | Prevale HubSpot | | **Nodale priority** | Nodale scrive, anche sopra un valore esistente | Come sopra; nulla torna indietro | Prevale Nodale | | **Deactivate sync** | Non passa nulla | Non passa nulla | Ciascuno mantiene il proprio | Per esempio, HubSpot ha «Marketing Manager» come ruolo, e il visitatore dice all'agente «Head of Growth». Con l'impostazione predefinita, HubSpot mantiene «Marketing Manager». Con Nodale priority, HubSpot riceve «Head of Growth». HubSpot rimanda valori a Nodale solo per nome, cognome, ruolo e campi di qualificazione. Una proprietà HubSpot di sola lettura può essere solo in HubSpot priority o disattivata. ## La nota di ogni conversazione Ogni conversazione diventa **una nota** in HubSpot, associata al contatto, alla sua azienda e alle trattative aperte del contatto. Viene scritta una volta e mai aggiornata. La sua data è l'inizio della conversazione. Scegli cosa contiene nella scheda **Note**. In ordine: | Blocco | Cosa contiene | Si può disattivare | |---|---|---| | Summary | Per cosa è venuto il visitatore e come è andata la conversazione. | No | | Next step | Cosa consiglia l'agente come passo successivo. | Sì | | Qualification criteria | I valori raccolti rispetto ai tuoi criteri. | Sì | | Qualification framework | Una breve riga per ogni pilastro del tuo framework (MEDDIC di default; SPICED, BANT, CHAMP o NEAT), scritta a partire dalla conversazione. Non viene mostrato quando qualifichi con un tuo elenco. | Sì | | Demos shown | Quali demo sono state riprodotte. | Sì | | Pages visited | Le pagine viste prima e durante la conversazione. | Sì | | Open the lead in Nodale | Un link al lead. | No | | Full transcript | L'intera conversazione, con righe che iniziano con «Visitor:» o «Agent:». | Sì | Tutti i blocchi sono attivi per impostazione predefinita. Una nota resta entro il limite di dimensione di HubSpot: prima viene accorciata la trascrizione («Transcript shortened, the full conversation is in Nodale.»), poi vengono esclusi gli ultimi blocchi. Il riepilogo e il link restano sempre. Quando il contenuto di una conversazione non viene più conservato, la sua nota esce senza la trascrizione. ## Trattative Nodale **non crea alcuna trattativa e non ne modifica nessuna**: nessun importo, nessuna fase, nessuna proprietà delle trattative. Allega la nota di ogni conversazione alle **trattative aperte** del contatto: le trattative del contatto nella tua pipeline predefinita (oppure, se questa non ha fasi aperte, nella prima pipeline che ne ha una) la cui fase non è chiusa. Un contatto appena creato da Nodale non ha ancora trattative, quindi la sua prima nota va solo al contatto e all'azienda. ## Prenota riunioni con HubSpot Meetings Durante la conversazione, l'agente può prenotare riunioni nei tuoi link per le riunioni HubSpot. Usa lo stesso collegamento HubSpot: non c'è nient'altro da installare. Un portale collegato prima di questa funzione mostra **To reconnect** sui suoi outcome di prenotazione: ricollega HubSpot una volta per concedere lo scope dei link per le riunioni. 1. In Nodale, apri **Agents**, poi la scheda **Outcomes**, e crea un **New outcome** di tipo **Meeting booking**. 2. Scegli un **Meeting type**. Ogni link per le riunioni HubSpot, personale o di team, è elencato una volta per ciascuna durata, per esempio «HubSpot Meetings · Intro call · 30 min». 3. Collega ogni domanda obbligatoria (**required question**) del link a un elemento che l'agente raccoglie. Il nome e l'email vengono compilati automaticamente. Una domanda di tipo telefono non è supportata: rendila facoltativa in HubSpot. Quando il visitatore ha fornito un'email di lavoro e il momento è giusto, l'agente propone degli orari nel suo fuso orario e nella sua lingua, e prenota quello che il visitatore sceglie. HubSpot crea la riunione con nome, email, fuso orario e risposte del visitatore, secondo le regole del link stesso (orari, preavviso, chi nel team è libero). Se nel frattempo l'orario è stato occupato, l'agente ne propone di nuovi. ![Gli orari che l'agente propone al visitatore nella conversazione](https://nodale.ai/assets/integrations/hubspot/booking.webp) Nodale non annulla né sposta le riunioni: lo si fa in HubSpot. ## Dati e scollegamento - Nodale scrive solo le proprietà che hai mappato, la nota e la proprietà azienda Nodale record ID. - Scollegare non elimina nulla in HubSpot. Nemmeno cancellare un lead in Nodale elimina qualcosa in HubSpot. - Domande: support@nodale.ai. ## Risoluzione dei problemi | Messaggio in Nodale | Cosa è successo | |---|---| | HubSpot was not connected: access was refused on the HubSpot page. | La pagina di consenso è stata chiusa o l'accesso è stato rifiutato. | | The HubSpot connection link expired or was already used. Start again from this page. | Il link è valido per dieci minuti, una sola volta. Clicca di nuovo su Connect HubSpot. | | HubSpot did not answer. Please try again in a few minutes. | HubSpot non era disponibile. | | HubSpot refused the connection. Please try again, or contact support if it keeps happening. | HubSpot ha rifiutato la richiesta. | | Couldn't connect HubSpot. Please try again. | Qualsiasi altro errore. |