SDK für Calling-Erweiterungen

ÜberblickEndpunkte

Bitte beachten: Unsere Anruf-App-Partner müssen Anrufinteraktionen nicht mehr manuell erstellen und aktualisieren; HubSpot erledigt dies für sie. Erfahren Sie dazu hier mehr.

Das SDK für Calling-Erweiterungen ermöglicht die Verwendung einer benutzerdefinierten Anrufoption für HubSpot-Benutzer direkt aus einem Datensatz im CRM. 

Eine Calling-Erweiterung besteht aus drei Hauptelementen:

  1. Das SDK für Calling-Erweiterungen, ein JavaScript-SDK, das die Kommunikation zwischen Ihrer App und HubSpot ermöglicht.
  2. Die Anrufeinstellungen-Endpunkte, die verwendet werden, um die Anrufeinstellungen für Ihre App festzulegen. Jeder HubSpot-Account, der mit Ihrer App verknüpft wird, verwendet diese Einstellungen.
  3. Das calling iframe, in dem Ihre App für HubSpot-Benutzer angezeigt wird und mit den Anrufeinstellungen konfiguriert wird.

Weitere Informationen zum In-App-Calling-Feature finden Sie in diesem Wissensdatenbankartikel. Sobald Ihre App mit Calling-Erweiterung mit HubSpot verknüpft ist, wird sie als Option in der Anrufumschaltung angezeigt, wenn ein Benutzer einen Anruf über HubSpot tätigt.

Wenn Sie über keine App verfügen, können Sie eine über Ihren HubSpot-Entwickler-Account erstellen. Wenn Sie noch keinen HubSpot-Entwickler-Account haben, können Sie sich hier für einen Account registrieren.

Bitte beachten: Derzeit werden nur ausgehende Anrufe unterstützt.

Die Demo-Anruf-App ausführen

Sie können das SDK für Calling-Erweiterungen mit zwei verschiedenen Demo-Apps testen:

  • Die demo-minimal-js bietet eine minimale Implementierung des SDK mit JavaScript, HTML und CSS. Zeigen Sie an, wie das SDK in index.js instanziiert wird.
  • Die demo-react-ts bietet eine praktische Implementierung des SDK mit React, TypeScript und Styled Components, um als Blaupause für Ihre App zu fungieren. Zeigen Sie an, wie das SDK in useCti.ts instanziiert wird.

Bitte beachten: Diese Demo-Apps sind keine voll funktionsfähigen Anruf-Apps und verwenden Scheindaten, um ein realistischeres Erlebnis zu bieten.

Die Demo-Anruf-App installieren

Sie können die Demo-Apps mit oder ohne Installation ausführen. So installieren Sie die Demo in Ihrer lokalen Umgebung:

  1. Installieren Sie Node.js in Ihrer Umgebung.
  2. Klonen Sie die ZIP-Datei dieses Repositorys, spalten Sie sie ab oder laden Sie sie herunter.
  3. Öffnen Sie Ihren Terminal und wechseln Sie zum Stammverzeichnis des Projekts.
  4. Führen Sie einen der folgenden Befehle aus:
      • Für die demo-minimal-js:
cd demos/demo-minimal-js && npm i && npm start
  • Für die demo-react-ts:
cd demos/demo-react-ts && npm i && npm start

Diese wechseln zum gewünschten Demo-Verzeichnis, installieren die für das Projekt erforderlichen Node.js-Abhängigkeiten mithilfe der npm CLI und starten die App. 

Bitte beachten: Der Befehl npm start öffnet automatisch eine neue Registerkarte in Ihrem Browser unter https://localhost:9025/, und Sie müssen möglicherweise eine Warnung vom Typ „Ihre Verbindung ist nicht sicher“ umgehen, um auf die Anwendung zugreifen zu können.

Die Demo-Anruf-App von HubSpot aus starten

  1. Gehen Sie zu Ihren Datensätzen:
    • Kontakte: Gehen Sie in Ihrem HubSpot-Account zu Kontakte > Kontakte.
    • Unternehmen: Gehen Sie in Ihrem HubSpot-Account zu Kontakte > Unternehmen.
  2. Öffnen Sie die Entwicklerkonsole Ihres Browsers und führen Sie den folgenden Befehl aus:
    • Wenn Sie die Installationsschritte abgeschlossen haben, für die demo-minimal-js oder die demo-react-ts:
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "local");
    • Wenn Sie die Installationsschritte übersprungen haben:
      • Für die demo-minimal-js:
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "app:js");
  • Für die demo-react-ts:
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "app");
  1. Aktualisieren Sie die Seite und klicken Sie auf das Telefon-Symbol in der linken Seitenleiste. Klicken Sie auf das Dropdown-Menü Anruf von und wählen Sie den Namen der Demo-App aus Schritt 2 aus (z. B. Demo-App Local, Demo-App JS, Demo-App React). 
    call-app-in-record
  2. Klicken Sie auf Anrufen, um zu sehen, wie sich die Demo-App über das SDK für Calling-Erweiterungen in HubSpot integrieren lässt. Sie können auch die Events anzeigen, die in der Entwicklerkonsole Ihres Browsers protokolliert werden.

call-sdk-in-app

 

Das SDK für Calling-Erweiterungen in Ihrer Anruf-App installieren

So fügen Sie das SDK für Calling-Erweiterungen als Node.js-Abhängigkeit zu Ihrer Anruf-App hinzu:

  • Führen Sie für npm Folgendes aus:
npm i --save @hubspot/calling-extensions-sdk
  • Führen Sie für yarn Folgendes aus:
yarn add @hubspot/calling-extensions-sdk

Typischer Nachrichtenfluss zwischen der Anruf-App und HubSpot

Das SDK für Calling-Erweiterungen stellt eine einfache API für HubSpot und eine Anruf-App zum Austausch von Nachrichten bereit. Die Nachrichten werden über Methoden gesendet, die vom SDK bereitgestellt werden, und über eventHandlersempfangen.

Im Folgenden werden die Events beschrieben:

  1. Nummer wählen: HubSpot sendet das Nummer-wählen-Event.
  2. Ausgehender Anruf gestartet: Die App benachrichtigt HubSpot, wenn der Anruf gestartet wird.
  3. Interaktion erstellen: HubSpot erstellt eine Anrufinteraktion mit minimalen Informationen, wenn dies von der App angefordert wird.
  4. Interaktion erstellt: HubSpot hat eine Interaktion erstellt.
  5. Interaktions-ID an App gesendet: HubSpot sendet die EngagementId an die App.
  6. Anruf beendet: Die App benachrichtigt, wenn der Anruf beendet ist.
  7. Anruf abgeschlossen: Die App benachrichtigt, wenn der Benutzer mit dem App-Benutzerlebnis fertig ist.
  8. Interaktion aktualisieren: Die App ruft die Interaktion anhand der engagementId ab und führt dann eine Zusammenführung durch und aktualisiert die Interaktion mit zusätzlichen Anrufdetails. Erfahren Sie mehr über das Aktualisieren einer Anrufinteraktion.

SDK für Calling-Erweiterungen verwenden

Eine Instanz erstellen

Erstellen Sie zunächst eine Instanz des CallingExtensions-Objekts. Sie können das Verhalten Ihrer Erweiterung definieren, indem Sie das Objekt einer Option angeben, wenn Sie Ihre Erweiterungeninstanz erstellen. Das Objekt dieser Option stellt ein eventHandlers-Feld bereit, in dem Sie das Verhalten Ihrer Erweiterung angeben können. Der folgende Code-Block veranschaulicht die verfügbaren Optionen und Event-Handler, die Sie definieren können:

import CallingExtensions from "@hubspot/calling-extensions-sdk"; const options = { /** @property {boolean} debugMode - Whether to log various inbound/outbound debug messages to the console. If false, console.debug will be used instead of console.log */ debugMode: true | false, // eventHandlers handle inbound messages eventHandlers: { onReady: () => { /* HubSpot is ready to receive messages. */ }, onDialNumber: event => { /* HubSpot sends a dial number from the contact */ }, /** onEngagementCreated will be @deprecated in 2024 */ onEngagementCreated: event => { /* HubSpot has created an engagement for this call. */ }, onCreateEngagementSucceeded: event => { /* HubSpot has created an engagement for this call. */ } onEngagementCreatedFailed: event => { /* HubSpot has failed to create an engagement for this call. */ } onUpdateEngagementSucceeded: event => { /* HubSpot has updated an engagement for this call. */ }, onUpdateEngagementFailed: event => { /* HubSpot has failed to update an engagement for this call. */ } onVisibilityChanged: event => { /* Call widget's visibility is changed. */ } } }; const extensions = new CallingExtensions(options);

Senden von Nachrichten an HubSpot

Das extensions-Objekt stellt die folgenden Event-Handler bereit, die Sie aufrufen können, um Nachrichten an HubSpot zu senden oder ein anderes zugeordnetes Verhalten anzugeben. Siehe folgende Beispiele.

  • initialized: Sendet eine Nachricht, die anzeigt, dass das Softphone für die Interaktion bereit ist. 
// The initialized call allows you to send a message indicating that the soft phone is ready for interaction. const payload = { // Whether a user is logged-in isLoggedIn: true|false, // Optionally send the desired widget size sizeInfo: { height: number, width: number } } extensions.initialized(payload);
  • userLoggedIn: Sendet eine Nachricht, dass sich der Benutzer angemeldet hat.
// Sends a message indicating that user has logged in // This message is only needed when user isn't loged in when initialized extensions.userLoggedIn();
  • userLoggedOut: Sendet eine Meldung, dass sich der Benutzer abgemeldet hat.
// Sends a message indicating that user has logged out extensions.userLoggedOut();
  • outgoingCall: Sendet eine Nachricht, um HubSpot zu informieren, dass ein ausgehender Anruf gestartet wurde. 
// Sends a message to notify HubSpot that an outgoing call has started. const callInfo = { phoneNumber: string, // optional unless call is initiated by the widget createEngagement: true, // whether HubSpot should create an engagement for this call callStartTime: number // optional unless call is initiated by the widget }; extensions.outgoingCall(callInfo);
  • callAnswered: Sendet eine Nachricht, um HubSpot zu informieren, dass ein ausgehender Anruf angenommen wird.
extensions.callAnswered();
  • callEnded: Sendet eine Nachricht, um HubSpot zu informieren, dass der Anruf beendet ist.
// Sends a message to notify HubSpot that the call has ended. // After receiving the call ended event, the user can navigate away, can close the call widget. extensions.callEnded();
  • callCompleted: Sendet eine Nachricht, um HubSpot zu informieren, dass der Anruf abgeschlossen ist. Für Interaktionseigenschaften ist HubSpot zuständig, d h., sie müssen nicht mehr manuell erstellt oder aktualisiert werden (siehe Hervorhebung).
Bitte beachten: Die hideWidget-Eigenschaft wird ignoriert, wenn sich der Benutzer in einer Aufgabenwarteschlange mit dem Aufgabentyp Call befindet.
// Sends a message to notify HubSpot that the call has completed. // After receiving the call completed event, HubSpot will // 1) insert the engagement into the timeline // 2) set the default associations on the engagement // 3) closes the widget unless `hideWidget` is set to false. // 4) update the engagement with any engagement properties const data = { engagementId: number, hideWidget: boolean, // (optional) defaults to true engagementProperties?: { [key: string]: string } // opt in to hs owned engagements by adding properties in https://developers.hubspot.com/docs/api/crm/calls#properties extensions.callCompleted(data);
  • sendError: Sendet eine Nachricht, um HubSpot zu informieren, dass in der Anruf-App ein Fehler aufgetreten ist.
// Sends a message to notify HubSpot that the call widget has encountered an error. // After receiving the sendError event, HubSpot will display an alert popup to the user with the error message provided. const data = { message: string // error message to be displayed in the alert popup }; extensions.sendError(data);
  • resizeWidget: Sendet eine Nachricht, um HubSpot zu informieren, dass die Größe der Anruf-App geändert werden muss.
// Sends a message to notify HubSpot that the call widget needs to be resized. // After receiving the resizeWidget event, HubSpot will use the provided height and width to resize the call widget. const data = { height: boolean // desired height of the call widget width: number, // desired width of the call widget }; extensions.resizeWidget(data);

Nachrichten von HubSpot empfangen

Das extensions-Objekt stellt die folgenden Event-Handler bereit, die Sie aufrufen können, um Nachrichten in HubSpot zu empfangen oder um ein anderes zugeordnetes Verhalten anzugeben. Siehe folgende Beispiele.

  • onReady: Nachricht, die angibt, dass HubSpot bereit ist, Nachrichten zu empfangen.
// Message indicating that HubSpot is ready to receive messages onReady() { // Send initialized message to HubSpot to indicate that the call widget is also ready extensions.initialized(payload); ... }
  • onDial: Nachricht, die angibt, dass der Benutzer einen ausgehenden Anruf ausgelöst hat.
// Message indicating that user has triggered an outbound call onDialNumber(data) { const { /* The phone nubmer to dial */ phoneNumber: string, /* The id of the logged in user. */ ownerId: number, /* The id of the hubspot account */ portalId: number, /* HubSpot object Id of the phoneNumber */ objectId: number, /* HubSpot object type of the phoneNumber */ objectType: CONTACT | COMPANY } = data; ... }
  • onEngagementCreated: Nachricht, die angibt, dass HubSpot onEngagementCreated-Daten erstellt hat.
Bitte beachten: HubSpot stellt das onEngagementCreated-Event zugunsten von onCreateEngagementSucceeded im Jahr 2024 ein.
/** @deprecated */ // Message indicating that HubSpot has created onEngagementCreated(data) { const { /* A HubSpot created engagement id. */ engagementId: number, } = data; ... }
  • onCreateEngagementSucceeded oder onCreateEngagementFailed (NEU): HubSpot sendet eine Nachricht, um den Anruf-App-Partner darüber zu informieren, dass das Erstellen der Interaktion erfolgreich war oder fehlgeschlagen ist.
onCreateEngagementSucceeded: event => { /* HubSpot has created an engagement for this call. */ }, onCreateEngagementFailed: event => { /* HubSpot has failed to create an engagement for this call. */ }
  • onUpdateEngagementSucceeded oder onUpdateEngagementFailed (NEU): HubSpot sendet eine Nachricht, um den Anruf-App-Partner darüber zu informieren, dass das Aktualisieren der Interaktion erfolgreich war oder fehlgeschlagen ist.
onUpdateEngagementSucceeded: event => { /* HubSpot has updated an engagement for this call. */ }, onUpdateEngagementFailed: event => { /* HubSpot has failed to update an engagement for this call. */ }
  • onVisibilityChanged: Nachricht, die angibt, ob der Benutzer die Anruf-App minimiert oder ausgeblendet hat.
// Message indicating if user has minimized/hide the call widget onVisibilityChanged(data) { const { isMinimized, isHidden } = data; ... }
  • defaultEventHandler: Standard-Handler für Events.
// Default handler for events. defaultEventHandler(event) { console.info("Event received. Do you need to handle it?", event); }

Ihre App testen

Um den Calling-Erweiterungen-iFrame für Endbenutzer zu starten, benötigt HubSpot die folgenden iFrame-Parameter.

{ name: string /* The name of your calling app to display to users. */, url: string /* The URL of your calling app, built with the Calling Extensions SDK */, width: number /* The iFrame's width */, height: number /* The iFrame's height */, isReady: boolean /* Whether the widget is ready for production (defaults to true) */, supportsCustomObjects : true /* Whether calls can be placed from a custom object */ }

Mithilfe des Anrufeinstellungen-Endpunkts

Senden Sie mit Ihrem API-Tool (z. B. Postman) die folgende Payload an die Einstellungen-API von HubSpot. Stellen Sie sicher, dass Sie die APP_ID Ihrer Anruf-App und den DEVELOPER_ACCOUNT_API_KEY Ihrer App abrufen.

Bitte beachten: Das isReady-Flag zeigt an, ob die App für die Produktion bereit ist. Dieses Flag sollte während des Testens auf false festlegt sein.
# Example payload to add the call widget app settings curl --request POST \ --url 'https://api.hubapi.com/crm/v3/extensions/calling/APP_ID/settings?hapikey=DEVELOPER_ACCOUNT_API_KEY' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{"name":"demo widget","url":"https://mywidget.com/widget","height":600,"width":400,"isReady":false}' # Note that this endpoint also supports PATCH, GET and DELETE

Ihre Erweiterungseinstellungen mit localStorage überschreiben

Sie können jede Ihrer Erweiterungseinstellungen zu Testzwecken außer Kraft setzen. Öffnen Sie Ihre Browser-Entwicklerkonsole über eine HubSpot-Registerkarte, bearbeiten Sie die folgenden Einstellungen und führen Sie den Befehl aus:

const myExtensionSettings = { isReady: true, name: "My app name", url: "My local/qa/prod URL", }; localStorage.setItem( "LocalSettings:Calling:CallingExtensions", myExtensionSettings, );

Ihre App für die Produktion vorbereiten

Wenn Sie den POST-Endpunkt bereits beim Testen Ihrer App verwendet haben, können Sie den PATCH-Endpunkt verwenden, um isReady in true zu ändern. Senden Sie ansonsten diese Payload mithilfe Ihres API-Tools (z. B. Postman) an die Einstellungen-API von HubSpot. Stellen Sie sicher, dass Sie die APP_ID Ihrer Anruf-App und den DEVELOPER_ACCOUNT_API_KEY Ihrer App abrufen.

# Example payload to add the call widget app settings curl --request POST \ --url 'https://api.hubapi.com/crm/v3/extensions/calling/APP_ID/settings?hapikey=DEVELOPER_ACCOUNT_API_KEY' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{"name":"demo widget","url":"https://mywidget.com/widget","height":600,"width":400,"isReady":true}' # Note that this endpoint also supports PATCH, GET and DELETE

Ihre Anruf-App im HubSpot Marketplace veröffentlichen

Der letzte Schritt nach der Einrichtung Ihrer App besteht darin, Ihre Anruf-App im HubSpot-Marketplace zu listen. Weitere Details finden Sie hier. Sie können sie auch nicht im Marketplace auflisten, wenn diese Anwendung nur für den internen Gebrauch bestimmt ist.

Calling-SDK | Häufig gestellte Fragen

How is user authentication handled?

Die Anruf-App sollte die Authentifizierung handhaben.

Is Calling Extensions hosted on a CDN?

Ja. Sie können das SDK für Calling-Erweiterungen über jsDeliver installieren. Um beispielsweise calling-extensions-sdk @0.2.2 zu installieren, können Sie https://cdn.jsdelivr.net/npm/@hubspot/calling-extensions-sdk@0.2.2/dist/main.js verwenden.

When should an engagement be created versus updated?

Ein Benutzer kann einen Anruf innerhalb der HubSpot-Benutzeroberfläche und außerhalb der HubSpot-Benutzeroberfläche initiieren (z. B. Mobile-App, weitergeleitete Nummer usw.). Wenn ein Anruf von der HubSpot-Benutzeroberfläche aus initiiert wird, erstellt HubSpot eine Anrufinteraktion und sendet die Interaktion an die Anruf-App. Sobald der Anruf beendet ist, kann die Anruf-App diese Interaktion mit zusätzlichen Anrufdetails aktualisieren. Wenn ein Anruf außerhalb der HubSpot-Benutzeroberfläche initiiert wird, sollte die App die Anrufinteraktion erstellen.

What scopes are required as a part of the integration?

Kontakte-hinzufügen- und Chronik-Bereiche sind erforderlich. Diese Bereiche stellen sicher, dass Ihre Anwendung Zugriff auf Kontakte hat und Anrufinteraktionen im CRM erstellen und aktualisieren kann.

Can this functionality be added to an already existing application in the marketplace or do I create a new app?

Wenn Sie bereits über eine bestehende App verfügen, die den Anwendungsfall „Anrufe“ bedient, können Sie diese Funktion direkt zu Ihrer bestehenden App hinzufügen. Alle Kunden, die Ihre App bereits installiert haben, erhalten Zugriff auf diese neue Funktion, ohne die App erneut installieren zu müssen.

Can I integrate my existing soft phone application in the SDK?

Ja, die Integration Ihrer vorhandenen Softphone-Anwendung sollte sehr einfach sein. Befolgen Sie einfach die Schritte in der obigen Dokumentation, um Ihre Anwendung einsatzbereit zu machen.

Can users use multiple integrations at the same time?

Ja, Benutzer können mehrere Anrufintegrationen von Drittanbietern gleichzeitig verwenden. Sie können mit dem Provider-Switcher, der nach dem Klicken auf die Anruftaste angezeigt wird, nahtlos zwischen den Anbietern wechseln.

Can free users install app integrations?

Ja, alle Benutzer können die App installieren.

If a user already has my app installed, does the integration automatically show up?

Ja, wenn ein Benutzer Ihre App bereits installiert hat und Sie dieselbe App mit den Calling-Erweiterungen aktualisieren, wird die Integration automatisch angezeigt. Derzeit gibt es keine Möglichkeit für den Entwickler, die Anruf-App nur für eine Teilmenge von Kunden zu aktivieren.

Can any user install or uninstall an app?

Nein, nur Benutzer mit den erforderlichen Berechtigungen können eine App installieren und deinstallieren. Erfahren Sie mehr darüber, wie Sie die Berechtigungen eines Benutzers überprüfen.

Can I place a call from a custom object?

Ja, Anrufintegrationen können Anrufe von benutzerdefinierten Objekten aus tätigen, solange sie nur das SDK zum Erstellen des Anrufs verwenden. Bei jeder Integration muss überprüft werden, ob sie nur das Anruf-SDK zum Erstellen von Anrufen und zum Benachrichtigen von HubSpot im outgoingCall-Event verwenden.

Stellen Sie zunächst sicher, dass die Integration das Anruf-SDK verwendet, um Interaktionen im outgoingCall-Event zu erstellen:

outgoingCall({ createEngagement: true })

Wenn createEngagement true ist, erfahren Sie hier, wie Sie Ihre App-Informationen aktualisieren.

Hier ist das Beispiel für das gesamte outgoingCall-Event:

const callInfo = { phoneNumber: string, // optional unless call is initiated by the widget createEngagement: true // whether HubSpot should create an engagement for this call callStartTime: number // optional unless call is initiated by the widget }; extensions.outgoingCall(callInfo);

Wenn Sie weitere Hilfe benötigen, besuchen Sie das HubSpot-Entwickler-Support-Forum.

War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.