HubSpot CRM Integration

Einführung

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

• Anrufer-ID zum Kontaktnamen – 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-Anrufdatensätze protokolliert.
• Einen neuen HubSpot-Kontakt erstellen direkt aus dem 3CX-Client bei Anrufen von neuen Nummern.
• Click-to-Call – starten Sie Anrufe direkt aus HubSpot über 3CX, indem Sie die 3CX Click2Call-Browsererweiterungen für Google Chrome und Microsoft Edge verwenden.

HubSpot CRM mit HubSpot CLI konfigurieren

HubSpot hat die Erstellung neuer legacy Public Apps über die Developer-Plattform-Schnittstelle eingestellt. Neue HubSpot-Apps müssen nun mit dem HubSpot Projects-Framework und dem HubSpot CLI erstellt werden.

Dieser Leitfaden erklärt, wie Sie die HubSpot OAuth-Anwendung erstellen, die für die 3CX HubSpot CRM-Integration erforderlich ist.

Hinweis: Bestehende legacy Public Apps funktionieren weiterhin.

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

Bevor Sie das HubSpot-Projekt erstellen, ermitteln Sie die öffentliche URL, die für den Zugriff auf das 3CX-System verwendet wird.

Wenn die 3CX Adminkonsole beispielsweise aufgerufen wird über:

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

...dann muss die HubSpot OAuth-Redirect-URL 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 sein.

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

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

npm install -g @hubspot/cli@latest



• Wenn die Installation abgeschlossen ist, überprüfen Sie die HubSpot CLI-Version:

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 aus:

hs account auth

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

• Geben Sie dem HubSpot-Konto bei Bedarf einen erkennbaren lokalen Namen.
• Ein Browserfenster öffnet sich, 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 an das Terminalfenster zurückgegeben werden.

• Wenn das CLI Sie auffordert, den Personal Access Key in das Terminal einzufügen, fügen Sie ihn ein und drücken Sie die Eingabetaste.

• Geben Sie einen Kontonamen ein, falls dazu aufgefordert wird.
• 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 aus:

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



• Das CLI wird nach zusätzlichen Informationen fragen.

• Projektname, Beispiel: "3CX HubSpot Integration"
• Lokaler Ordner, Standard oder verwenden Sie etwas Einfaches wie: "3cx-hubspot"
• Funktionen

• Die 3CX CRM-Integration selbst benötigt keine HubSpot App Card, Webhook, Workflow-Aktion, Einstellungsseite oder andere Projektfunktionen. Wenn das CLI Sie auffordert, Funktionen auszuwählen, lassen Sie alle Funktionen unmarkiert und fahren Sie fort, indem Sie die Eingabetaste drücken.

• Nachdem der Befehl abgeschlossen ist, sollte ein neues Verzeichnis existieren, z. B.: "C:\HubSpotProjects\3cx-hubspot"
• Wechseln Sie in dieses Verzeichnis:

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



• Zu den wichtigen Dateien gehören:

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 Notepad: "C:\HubSpotProjects\3cx-hubspot\src\app\app-hsmeta.json".

Die generierte Datei kann zusätzliche Eigenschaften enthalten, die ignoriert werden können; der wichtige Abschnitt ist die config der Anwendung und insbesondere der Abschnitt auth.

Konfigurieren Sie die App mit Ihren distribution, requiredScopes und redirectUrls wie unten gezeigt, und ersetzen Sie "https://pbx.example.com/api/oauth2crm" durch die tatsächliche öffentliche 3CX-URL, die in Schritt 1 ermittelt wurde.

{

  "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 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 aus:

hs project upload



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

• "Das Projekt existiert in diesem Konto nicht. Möchten Sie es erstellen?"

• 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 in Ihrem Browser bei Ihrem HubSpot an und navigieren Sie zu Development > Projects
• Öffnen Sie 3CX HubSpot Integration (oder den von Ihnen erstellten Projektnamen).
• Klicken Sie unter Projektkomponenten auf den Namen der Anwendung.
• Öffnen Sie den Reiter Auth.

• HubSpot zeigt die folgenden Client-Anmeldedaten an:

• Client ID
• Client secret (Client-Geheimnis)

• 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 explizit genehmigt wurden. Standardmäßig hat nur das Konto, das die App erstellt hat, Zugriff ("privat").

In HubSpot:

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

• Öffnen Sie den Reiter Distribution.

• Klicken Sie auf Add approved account(s) (Genehmigte 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 Zugriff sowohl auf ein Entwicklungskonto als auch auf das normale CRM-Konto des Unternehmens hat, stellen Sie sicher, dass das CRM-Konto genehmigt ist, das die tatsächlichen Kundendaten enthält.

• Klicken Sie auf Save changes (Änderungen speichern).

HubSpot in 3CX konfigurieren und autorisieren

1. Gehen Sie in der 3CX Adminkonsole auf "Integrations" > "CRM".
2. Wählen Sie "HubSpot" aus der Dropdown-Liste aus.
3. Wählen Sie die gewünschte Suchreihenfolge für Kontakte (Contact Lookup Order)
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 erwartet, wenn eine Anwendung 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-Token aus.
• Überprüfen Sie, ob das Feld "Refresh Token" für das HubSpot CRM in der 3CX Adminkonsole automatisch ausgefüllt wurde.
• 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 Suchen nach der vollständigen Nummer durchführt. Die Abfrage von HubSpot mit einem Teil der Ziffern liefert 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. Wenn dies nicht der Fall ist, können Sie Anrufer-ID-Neuformatierung verwenden, um die Nummer des Anrufers anzupassen, bevor sie an das CRM übermittelt wird.
3. Gehen Sie nun zu System > Telefonbuch > Optionen, stellen Sie die Übereinstimmungsstrategie auf "Genau übereinstimmen" 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 erhält, 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. Verpasster Anruf - Beschreibung für verpasste Anrufe.
4. Beantworteter ausgehender Anruf - Beschreibung für beantwortete ausgehende Anrufe.
5. Unbeantworteter ausgehender Anruf - Beschreibung für unbeantwortete ausgehende Anrufe.

3. Bitte beachten Sie, dass Sie Variablen in den Parametern der "Anruf-Journalisierung" verwenden können, die als
   [variablen_name]
   gekennzeichnet sind, z. B. wird die externe Nummer als
   [Number]
   angegeben. Die verfügbaren Variablen sind hier aufgeführt.

4. Wenn Sie Chats an das CRM melden möchten, aktivieren Sie das Kontrollkästchen "Chat-Journalisierung aktivieren" und konfigurieren Sie die unten stehenden Parameter:

1. Chat-Betreff - der Betreff der Chat-Sitzung.

5. Bitte beachten Sie, dass Sie Variablen in den Parametern der "Chat-Journalisierung" verwenden können, die als
   [variablen_name]
   gekennzeichnet sind, z. B. wird die externe Nummer als
   [Number]
   angegeben. Die verfügbaren Variablen sind hier aufgeführt.

Siehe auch

• Integration ihres CRM mit der 3CX API
• Bitrix24-Integration
• ConnectWise-Integration
• Microsoft 365 Integration
• Jetpack CRM-Integration
• Salesforce-Integration.
• Zoho-Integration.

Letztes Update

Dieses Dokument wurde zuletzt am 25. August 2026 aktualisiert.

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