HubSpot CRM Integration

Einführung


3CX bietet die Integration mit HubSpot über die 3CX API für CRM mit den folgenden Funktionen:

  • Anrufer-ID zu Kontaktname – eingehende Anrufe lösen eine HubSpot-Kontaktsuche aus.
  • Kontaktsuche in HubSpot basierend auf Name, Nummer oder E-Mail, wenn Sie im 3CX Webclient nach einem Namen suchen.
  • Anruf- & Chat-Journalisierung – Anrufe und Chats werden in der HubSpot-Kontaktkarte als CRM-Anrufeinträge protokolliert.
  • Neuen HubSpot-Kontakt erstellen aus dem 3CX-Client für Anrufe von neuen Nummern.
  • Click-to-Call – starten Sie Anrufe direkt aus HubSpot über 3CX mit den 3CX Click2Call-Browser-Erweiterungen für Google Chrome und Microsoft Edge.

HubSpot CRM mit HubSpot CLI konfigurieren

HubSpot hat die Erstellung neuer Legacy Public Apps über die Developer Platform-Oberfläche eingestellt. Neue HubSpot-Apps müssen nun mit dem Projects-Framework von HubSpot und der HubSpot CLI erstellt werden.

Diese Anleitung erklärt, wie Sie die von der 3CX HubSpot CRM-Integration benötigte HubSpot OAuth-Anwendung erstellen.

Hinweis: Bestehende Legacy Public Apps funktionieren weiterhin.

Schritt 1: Ermitteln Sie die 3CX OAuth-Redirect-URL

Ermitteln Sie vor dem Erstellen des HubSpot-Projekts die öffentliche URL, über die auf das 3CX-System zugegriffen wird.

Wenn beispielsweise auf die 3CX-Admin-Konsole zugegriffen wird über:

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

...dann muss die HubSpot OAuth-Redirect-URL wie folgt lauten:

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

Schritt 2: Installieren Sie das HubSpot CLI

Das HubSpot CLI ist eine Node.js-Anwendung, daher muss zuerst Node.js mit npm installiert werden.

HubSpot CLI 8 erfordert Node.js 20 oder höher.

  • Öffnen Sie eine neue Eingabeaufforderung.
  • Führen Sie in der Eingabeaufforderung Folgendes aus:

npm install -g @hubspot/cli@latest

  • Überprüfen Sie nach Abschluss der Installation die Version des HubSpot CLI:

hs --version

  • Eine HubSpot CLI-Version sollte angezeigt werden.

Schritt 3: Melden Sie sich über das CLI bei HubSpot an

  • Führen Sie in der Eingabeaufforderung Folgendes aus:

hs account auth

Das CLI führt Sie durch die Authentifizierung Ihres HubSpot-Kontos. Folgen Sie den Anweisungen:

  • Geben Sie dem HubSpot-Konto bei Aufforderung einen wiedererkennbaren lokalen Namen.
  • Ein Browserfenster wird geöffnet oder das CLI zeigt Anweisungen zum Öffnen von HubSpot an.
  • Melden Sie sich bei dem HubSpot-Konto an, in dem das Projekt/die Anwendung erstellt werden soll.

  • Generieren Sie den angeforderten Personal Access Key.
  • Der Schlüssel sollte automatisch im Terminalfenster zurückgegeben werden.
  • Wenn Sie vom CLI aufgefordert werden, den Personal Access Key in das Terminal einzufügen, fügen Sie ihn ein und drücken Sie die Eingabetaste.
  • Geben Sie bei Aufforderung einen Kontonamen ein.
  • Wenn Sie gefragt werden, ob dies das Standardkonto sein soll, wählen Sie Ja.

Schritt 4: Erstellen Sie das HubSpot OAuth-Projekt

  • In der Eingabeaufforderung
  • Erstellen Sie einen Projektordner, z. B.:

mkdir C:\HubSpotProjects

cd /d C:\HubSpotProjects

  • Führen Sie in diesem Ordner Folgendes aus:

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

  • Das CLI fragt nach zusätzlichen Informationen.

  • Projektname, Beispiel: "3CX HubSpot Integration"
  • Lokaler Ordner, Standard oder etwas Einfaches verwenden wie: "3cx-hubspot"
  • Funktionen
  • Die 3CX CRM-Integration selbst erfordert keine HubSpot-App-Karte, keinen Webhook, keine Workflow-Aktion, keine Einstellungsseite oder andere Projektfunktionen. Wenn das CLI Sie auffordert, Funktionen auszuwählen, lassen Sie alle Funktionen unausgewählt und fahren Sie fort, indem Sie die Eingabetaste drücken.

  • Nach Abschluss des Befehls sollte ein neues Verzeichnis existieren, z. B.: "C:\HubSpotProjects\3cx-hubspot"
  • Wechseln Sie in dieses Verzeichnis:

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

  • Die wichtigen Dateien sollten Folgendes umfassen:

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

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

Schritt 5: Konfigurieren Sie OAuth und die erforderlichen Berechtigungen für 3CX

Öffnen Sie die folgende Datei in Editor: "C:\HubSpotProjects\3cx-hubspot\src\app\app-hsmeta.json".

Die generierte Datei enthält möglicherweise zusätzliche Eigenschaften, die ignoriert werden können. Der wichtige Abschnitt ist die config der Anwendung und insbesondere der Abschnitt auth.

Konfigurieren Sie die App mit Ihrer distribution, den requiredScopes und den redirectUrls wie unten gezeigt und ersetzen Sie "https://pbx.example.com/api/oauth2crm" durch die tatsächliche öffentliche 3CX-URL aus Schritt 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"

    }

  }

}

Schritt 6: Validieren und laden Sie das Projekt zu HubSpot hoch

  • Führen Sie im Projektverzeichnis Folgendes aus:

hs project validate

  • Wenn die Validierung erfolgreich ist, fahren Sie fort.
  • Wenn die Validierung einen Fehler meldet, korrigieren Sie die angegebene JSON-Eigenschaft und führen Sie den Befehl erneut aus.
  • Führen Sie dann Folgendes aus:

hs project upload

  • Beim ersten Hochladen des Projekts zeigt HubSpot möglicherweise eine Meldung an wie:

  • "The project does not exist in this account. Would you like to create it?"
  • Antworten Sie mit "Y" und fahren Sie fort.
  • Das CLI wird:
  • die Dateien hochladen
  • einen HubSpot-Build erstellen
  • die Anwendung bereitstellen

Schritt 7: Erhalten Sie die Client-ID und das Client-Secret in HubSpot

  • Melden Sie sich im Browser bei HubSpot an und navigieren Sie zu Development > Projects
  • Öffnen Sie 3CX HubSpot Integration (oder den von Ihnen erstellten Projektnamen).
  • Klicken Sie unter Project Components auf den Namen der Anwendung.
  • Öffnen Sie die Registerkarte Auth.

  • HubSpot zeigt die folgenden Client-Anmeldedaten an:
  • Client-ID
  • Client-Secret
  • Kopieren Sie beide Werte an einen sicheren Ort.

Schritt 8: Zusätzliche HubSpot CRM-Konten zur privaten OAuth-App hinzufügen (Optional)

Dies ist ein wichtiger neuer Schritt im Vergleich zum alten Verfahren für Public Apps.

Da das Projekt mit "distribution": "private" erstellt wurde, erlaubt HubSpot die OAuth-Autorisierung nur für Konten, die ausdrücklich genehmigt wurden. Standardmäßig hat nur das Konto Zugriff, das die App erstellt hat ("private").

In HubSpot:

  • Öffnen Sie Development.
  • Öffnen Sie Projects.
  • Öffnen Sie das 3CX-Projekt.
  • Wählen Sie unter Project Components die 3CX-Anwendung aus.

  • Öffnen Sie die Registerkarte Distribution.
  • Klicken Sie auf Genehmigte(s) Konto/Konten hinzufügen.
  • Wählen Sie unter den verfügbaren Produktionskonten das HubSpot CRM-Konto aus, das die Kontakte und Unternehmen enthält, die mit 3CX integriert werden sollen.
  • Wenn Ihr HubSpot-Login sowohl Zugriff auf ein Entwicklerkonto als auch auf das normale CRM-Konto des Unternehmens hat, stellen Sie sicher, dass das CRM-Konto mit den tatsächlichen Kundendaten genehmigt wird.
  • Klicken Sie auf Änderungen speichern.

HubSpot in 3CX konfigurieren und autorisieren

  1. Gehen Sie zu 3CX Admin-Konsole > Integrationen > CRM.
  2. Wählen Sie "HubSpot" aus der Dropdown-Liste aus.
  3. Wählen Sie die gewünschte Kontaktsuchreihenfolge aus
  4. Geben Sie die zuvor aus Ihrer App kopierten OAuth-Werte für "Client-ID" und "Client-Secret" ein.
  5. Klicken Sie auf Speichern
  6. Klicken Sie auf Autorisieren

  • Eine HubSpot-Autorisierungsseite sollte sich öffnen.
  • Melden Sie sich bei Bedarf bei HubSpot an.
  • Wählen Sie das HubSpot CRM-Konto aus, das die Kontakte und Unternehmen enthält, die von 3CX verwendet werden sollen.
  • Überprüfen Sie die angeforderten Berechtigungen.
  • HubSpot warnt möglicherweise, dass die Anwendung nicht verifiziert ist. Dies wird für eine Anwendung erwartet, die für Ihr eigenes Konto erstellt und nicht im HubSpot-Marketplace eingereicht wurde.
  • Bestätigen Sie die Installation/Autorisierung.
  • 3CX erhält nun den OAuth-Autorisierungscode und tauscht ihn gegen HubSpot OAuth-Tokens aus.
  • Überprüfen Sie, ob das Feld "Refresh Token" für das HubSpot CRM in der 3CX Admin-Konsole automatisch ausgefüllt wird.
  • Wenn Sie die Kontakterstellung über den 3CX-Client aktivieren möchten, aktivieren Sie diese Option. Wenn die Nummer des Anrufers keinem Kontakt zugeordnet werden kann, ermöglicht der 3CX-Client dem Nutzer, den Kontakt durch Ausfüllen der Details in einem Dialogfeld zu erstellen.

e164-Kontakte und Anrufer-ID konfigurieren

  1. Um eine Übereinstimmung mit HubSpot zu erzielen, muss die eingehende Anrufer-ID identisch mit dem CRM-Eintrag sein, einschließlich etwaiger Präfixe, da HubSpot vollständige Nummernsuchen durchführt. Das Abfragen von HubSpot unter Verwendung einer Teilmenge der Ziffern gibt keine Daten zurück.
  2. Damit die HubSpot-Integration funktioniert, müssen Sie die Nummern in HubSpot im E164-Format speichern, und Ihr SIP-Trunk muss die Nummer des Anrufers ebenfalls im E164-Format bereitstellen, damit beide übereinstimmen. Ist dies nicht der Fall, können Sie die Anrufer-ID-Neuformatierung verwenden, um die Nummer des Anrufers anzupassen, bevor sie an das CRM übergeben wird.
  3. Gehen Sie zu Admin > System > Telefonbuch > Optionen, stellen Sie die Match-Strategie auf "Exakt vergleichen" ein und klicken Sie auf "OK".

Anruf- & Chat-Journalisierung konfigurieren, einschließlich Transkription

  1. Um externe Anrufe und Chats an HubSpot zu melden, muss die für die 3CX-Nebenstelle konfigurierte E-Mail-Adresse mit der E-Mail-Adresse eines HubSpot-Nutzers übereinstimmen. Auf diese Weise kann 3CX die 3CX-Nebenstelle, die den Anruf oder Chat empfängt, dem HubSpot-Nutzer zuordnen.
  2. Aktivieren Sie die Option "Anruf-Journalisierung aktivieren", um externe Anrufe an das CRM zu melden, und konfigurieren Sie diese Parameter für die "Anruf-Journalisierung":
  1. Anrufbetreff – der Betreff des Anrufs.
  2. Beantworteter eingehender Anruf – Beschreibung für beantwortete eingehende Anrufe.
  3. Entgangener Anruf – Beschreibung für entgangene Anrufe.
  4. Beantworteter ausgehender Anruf – Beschreibung für beantwortete ausgehende Anrufe.
  5. Unbeantworteter ausgehender Anruf – Beschreibung für unbeantwortete ausgehende Anrufe.
  1. Bitte beachten Sie, dass Sie Variablen in den Parametern für die "Anruf-Journalisierung" verwenden können, die als
    [variable_name]
    angegeben werden, z. B. wird die externe Nummer als
    [Number]
    angegeben. Die verfügbaren Variablen sind     hier aufgelistet.

  1. Wenn Sie Chats an das CRM melden möchten, aktivieren Sie das Kontrollkästchen "Chat-Journalisierung aktivieren" und konfigurieren Sie die folgenden Parameter:
  1. Chat-Betreff – der Betreff der Chat-Sitzung.
  1. Bitte beachten Sie, dass Sie Variablen in den Parametern für die "Chat-Journalisierung" verwenden können, die als
    [variable_name]
    angegeben werden, z. B. wird die externe Nummer als
    [Number]
    angegeben. Die verfügbaren Variablen sind     hier aufgelistet.

Siehe auch

Letztes Update

Dieses Dokument wurde zuletzt am 29. September 2026 aktualisiert.

https://www.3cx.de/docs/hubspot-pbx-crm-integration/