Integrazione CRM HubSpot

Introduzione

Hub spot integrazione

3CX offre l'integrazione con HubSpot tramite l'API 3CX per CRM con le seguenti caratteristiche:

  • ID chiamante a nome del contatto: Le chiamate in entrata avviano una ricerca del contatto in HubSpot.
  • Ricerca del contatto in HubSpot in base al nome, al numero o all'email se si cerca un nome nel 3CX Webclient.
  • Call & Chat Journalling: Le chiamate e le chat vengono registrate nella scheda contatti di HubSpot come record di chiamata del CRM.
  • Creare un nuovo contatto HubSpot dal client 3CX per le chiamate da nuovi numeri.
  • Click to Call: Avviare le chiamate direttamente da HubSpot tramite 3CX, utilizzando le estensioni del browser 3CX Click2Call per Google Chrome e Microsoft Edge.

Configurare HubSpot CRM con HubSpot CLI

HubSpot ha interrotto la creazione di nuove app pubbliche legacy dall'interfaccia della Piattaforma per sviluppatori. Le nuove app HubSpot devono ora essere create utilizzando il framework Projects di HubSpot e HubSpot CLI.

Questa guida spiega come creare l'applicazione OAuth di HubSpot richiesta dall'integrazione 3CX con HubSpot CRM.

Nota: le app pubbliche legacy esistenti continuano a funzionare.

Passo 1: Individuare l’URL di reindirizzamento OAuth di 3CX

Prima di creare il progetto HubSpot, individuare l’URL pubblico utilizzato per accedere al sistema 3CX.

Ad esempio, se si accede alla console di amministrazione di 3CX tramite:

https://mypbx.3cx-example.com

...allora l’URL di reindirizzamento OAuth di HubSpot deve essere:

https://mypbx.3cx-example.com/api/oauth2crm

Passo 2: installare la CLI di HubSpot

La CLI di HubSpot è un’applicazione Node.js, quindi è necessario installare prima Node.js con npm.

La CLI di HubSpot 8 richiede Node.js 20 o versioni successive.

  • Apri un nuovo Prompt dei comandi.
  • Nel Prompt dei comandi, esegui:

npm install -g @hubspot/cli@latest

  • Al termine dell'installazione, verifica la versione della CLI di HubSpot:

hs --version

  • Dovrebbe essere visualizzata una versione della CLI di HubSpot.

Passo 3: Accedere a HubSpot dalla CLI

  • Nel Prompt dei comandi, esegui:

hs account auth

La CLI ti guiderà attraverso la procedura di autenticazione del tuo account HubSpot. Segui le istruzioni:

  • Se richiesto, assegna all’account HubSpot un nome locale riconoscibile.
  • Si aprirà una finestra del browser oppure la CLI visualizzerà le istruzioni per aprire HubSpot.
  • Accedi all’account HubSpot in cui verrà creato il progetto/l’applicazione.

  • Genera la chiave di accesso personale richiesta.
  • La chiave dovrebbe essere visualizzata automaticamente nella finestra del terminale.
  • Se l'interfaccia CLI ti chiede di incollare la chiave di accesso personale nel terminale, incollala e premi Invio.
  • Inserisci un nome per l'account se richiesto.
  • Se ti viene chiesto se questo deve essere l'account predefinito, seleziona Sì.

Passo 4: Creare il progetto OAuth di HubSpot

  • Nel Prompt dei comandi
  • Crea una cartella per il progetto, ad esempio:

mkdir C:\HubSpotProjects

cd /d C:\HubSpotProjects

  • In questa cartella, esegui:

hs project create --project-base app --distribution private --auth oauth

  • La CLI richiederà ulteriori informazioni.

  • Nome del progetto, ad esempio: “3CX HubSpot Integration”
  • Cartella locale, quella predefinita  oppure usa qualcosa di semplice come: “3cx-hubspot”
  • Funzionalità
  • L'integrazione CRM di 3CX di per sé non richiede una HubSpot App Card, un webhook, un'azione di flusso di lavoro, una pagina delle impostazioni o altre funzionalità del progetto. Se la CLI ti chiede di scegliere delle funzionalità, lascia tutte le opzioni deselezionate e prosegui premendo Invio.

  • Una volta completato il comando, dovrebbe essere presente una nuova directory, ad esempio: “C:\HubSpotProjects\3cx-hubspot”
  • Passa a quella directory:

cd /d C:\HubSpotProjects\3cx-hubspot

  • I file importanti dovrebbero includere:

C:\HubSpotProjects\3cx-hubspot\hsproject.json

C:\HubSpotProjects\3cx-hubspot\src\app\app-hsmeta.json

Passo 5: Configurare OAuth e gli ambiti richiesti per 3CX

Aprire il seguente file in Blocco note: “C:\HubSpotProjects\3cx-hubspot\src\app\app-hsmeta.json”.

Il file generato potrebbe contenere proprietà aggiuntive che possono essere ignorate; la sezione importante è quella relativa alla configurazione dell’applicazione e, in particolare, la sezione “auth”

Configura l’app con i valori relativi a distribution, requiredScopes e redirectUrls come mostrato di seguito, sostituendo “https://pbx.example.com/api/oauth2crm” con l’URL pubblico effettivo di 3CX determinato nel Passo 1.

{

  "uid": "3CXHubSpotIntegration_app",

  "type": "app",

  "config": {

    "description": "OAuth application for the 3CX HubSpot CRM integration",

    "name": "3CX HubSpot Integration-App",

    "distribution": "private",

    "auth": {

      "type": "oauth",

      "redirectUrls": [

        "https://pbx.example.com/api/oauth2crm"

      ],

      "requiredScopes": [

      "oath",

           "crm.objects.contacts.read",

                "crm.objects.contacts.write",

                "crm.objects.companies.read",

                "crm.objects.owners.read",

                "timeline"

      ],

      "optionalScopes": [],

      "conditionallyRequiredScopes": []

    },

    "permittedUrls": {

      "fetch": [

        "https://api.hubapi.com"

      ],

      "iframe": [],

      "img": []

    },

    "support": {

      "supportEmail": "[email protected]",

      "documentationUrl": "https://example.com/docs",

      "supportUrl": "https://example.com/support",

      "supportPhone": "+18005555555"

    }

  }

}

Passo 6: Convalidare e caricare il progetto su HubSpot

  • Se la convalida va a buon fine, prosegui.

hs project validate

  • If validation succeeds, continue.
  • Se la convalida segnala un errore, correggi la proprietà JSON indicata ed esegui nuovamente il comando.
  • Quindi esegui:

hs project upload

  • La prima volta che il progetto viene caricato, HubSpot potrebbe visualizzare un messaggio simile a:

  • “Il progetto non esiste in questo account. Vuoi crearlo?”
  • Rispondi “Y” e prosegui.
  • La CLI provvederà a:
  • Caricare i file
  • Creare una build HubSpot
  • Distribuire l’applicazione

Passo 7: Ottenere l’ID cliente e il segreto cliente in HubSpot

  • Nel browser, accedi al tuo account HubSpot e vai su Sviluppo > Progetti
  • Apri Integrazione 3CX con HubSpot (o il nome del progetto che hai creato).
  • Nella sezione Componenti del progetto, clicca sul nome dell’applicazione.
  • Apri la scheda Autenticazione.

  • HubSpot mostrerà le seguenti credenziali del cliente:
  • ID cliente
  • Segreto cliente
  • Copia entrambi i valori in un luogo sicuro.

Passo 8: Aggiungere ulteriori account CRM HubSpot all’app OAuth privata (facoltativo)

Si tratta di un nuovo passaggio importante rispetto alla precedente procedura per le app pubbliche.

Poiché il progetto è stato creato con “distribution”: ‘private’, HubSpot consente l’autorizzazione OAuth solo per gli account che sono stati esplicitamente approvati. Per impostazione predefinita, solo l’account che ha creato l’app ha accesso (“private”).

In HubSpot:

  • Apri Sviluppo.
  • Apri Progetti.
  • Apri il progetto 3CX.
  • In Componenti del progetto, seleziona l’applicazione 3CX.

  • Apri la scheda Distribuzione.
  • Clicca su Aggiungi account approvati.
  • Tra gli account di produzione disponibili, seleziona l’account HubSpot CRM che contiene i contatti e le aziende che verranno integrati con 3CX.
  • Se il tuo account HubSpot ha accesso sia a un account di sviluppo che al normale account CRM dell’azienda, assicurati che sia approvato l’account CRM contenente i dati effettivi dei clienti.
  • Clicca su Salva modifiche.

Configurare e autorizzare HubSpot in 3CX

  1. Nella console di amministrazione di 3CX, vai su Integrazioni” > CRM.
  2. Seleziona HubSpot dall'elenco a discesa.
  3. Seleziona l'ordine di ricerca dei contatti desiderato.
  4. Inserisci i valori OAuth precedentemente copiati dalla tua app nei campi “ID cliente” e “Client segreto”.
  5. Clicca su Salva.
  6. Clicca su Autorizza.

  • Dovrebbe aprirsi una pagina di autorizzazione di HubSpot.
  • Accedi a HubSpot se richiesto.
  • Seleziona l’account CRM di HubSpot contenente i contatti e le aziende che devono essere utilizzati da 3CX.
  • Verifica le autorizzazioni richieste.
  • HubSpot potrebbe avvisarti che l’applicazione non è verificata. Ciò è normale per un’applicazione creata per il tuo account personale e non pubblicata su HubSpot Marketplace.
  • Conferma l’installazione/autorizzazione.
  • 3CX riceve ora il codice di autorizzazione OAuth e lo scambia con i token OAuth di HubSpot.
  • Verifica che il campo Token di aggiornamento sia compilato automaticamente per HubSpot CRM nella console di amministrazione di 3CX.
  • Se desideri abilitare la creazione di contatti dal client 3CX, seleziona questa opzione. Quando il numero del chiamante non può essere associato a un contatto, il client 3CX consentirà all’utente di creare il contatto inserendo i dettagli in una finestra di dialogo.

Configurazione dei contatti e164 e dell’ID chiamante

  1. Per ottenere una corrispondenza con HubSpot, l’ID chiamante in entrata deve essere identico alla voce presente nel CRM, compreso l’eventuale prefisso, poiché HubSpot esegue ricerche sul numero completo. L’interrogazione di HubSpot utilizzando solo una parte delle cifre non restituisce alcun dato.
  2. Affinché l’integrazione con HubSpot funzioni, è necessario memorizzare i numeri in HubSpot utilizzando il formato E164 e il trunk SIP deve fornire il numero del chiamante anch’esso in formato E164, in modo che entrambi corrispondano. Se ciò non avviene, è possibile utilizzare la riformattazione dell’ID chiamante per modificare il numero del chiamante prima che venga trasmesso al CRM.
  3. Ora vai su Sistema > Rubrica > Opzioni, imposta la strategia di corrispondenza su Corrispondenza esatta e clicca su OK.

Configura la registrazione di chiamate e chat, inclusa la trascrizione

  1. Per segnalare le chiamate e le chat esterne a HubSpot, l’indirizzo e-mail configurato per l’estensione 3CX deve corrispondere all’indirizzo e-mail di un utente HubSpot. In questo modo 3CX può associare l’estensione 3CX che riceve la chiamata o la chat all’utente HubSpot.
  2. Seleziona l’opzione Abilita registrazione delle chiamate per segnalare le chiamate esterne al CRM e configura i seguenti parametri di Registrazione delle chiamate:
  1. Oggetto della chiamata: L'oggetto della chiamata.
  2. Chiamata in entrata risposta: Descrizione delle chiamate in entrata a cui è stata data risposta.
  3. Chiamata persa: Descrizione delle chiamate perse.
  4. Chiamata in uscita risposta: Descrizione delle chiamate in uscita a cui è stata data risposta.
  5. Chiamata in uscita senza risposta: Descrizione delle chiamate in uscita a cui non è stata data risposta.
  1. Si noti che è possibile utilizzare variabili nei parametri di “Registrazione delle chiamate”, indicate come [codice][nome_variabile][/codice]; ad esempio, il numero esterno viene specificato come [codice][Numero][/codice]. Le variabili disponibili sono elencate qui.

  1. Se desideri registrare le chat nel CRM, seleziona la casella di controllo “Abilita registrazione chat” e configura i parametri riportati di seguito:
  1. Oggetto della chat: L'oggetto della sessione di chat.
  1. Si noti che è possibile utilizzare variabili nei parametri della “Registrazione delle chat”, indicate come
    [nome_variabile]
    ; ad esempio, il numero esterno viene specificato come
    [Numero]
    . Le variabili disponibili sono elencate     qui.

Per saperne di più

Ultimo aggiornamento

Questo documento è stato aggiornato il 25 agosto 2026

https://www.3cx.it/doc/integrazione-crm-hubspot/ 

Discuti questo articolo