SDK für Calling-Erweiterungen

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 Endpunkte der Calling-Einstellungen, die verwendet werden, um die Calling-Einstellungen für Ihre App festzulegen. Jeder mit Ihrer App verknüpfte HubSpot-Account verwendet diese Einstellungen.
  3. Das calling iframe, in dem Ihre App für HubSpot-Benutzer angezeigt wird und mit den Calling-Einstellungen konfiguriert wird.

Weitere Informationen zum In-App-Calling-Feature finden Sie in diesem Wissensdatenbank-Artikel. 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.

Please note: only outgoing calls are currently supported.

SDK für Calling-Erweiterungen

Das SDK für Calling-Erweiterungen ist eine JavaScript-Bibliothek, die zur Kommunikation zwischen HubSpot und Ihrer Calling-App verwendet wird. Sie wird in einem iframe angezeigt. Diese Kommunikation umfasst:

  • HubSpot benachrichtigt Ihre App, welche Nummer angerufen werden soll.
  • Ihre App benachrichtigt HubSpot, wann der Anruf verbunden und wann er beendet ist.
  • HubSpot benachrichtigt Ihre App über die Platzhalter-Interaktions-ID, die mit den Anrufdetails aktualisiert werden muss.

Sie finden das SDK in diesem GitHub-Repository zusammen mit den technischen Anforderungen und den Einzelheiten zur Nutzung für das SDK in Ihrer Web-App.

Setup

Calling-Erweiterungen werden als Teil einer HubSpot-App konfiguriert. 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.

Sobald Sie die Calling-Einstellungen für Ihre App konfiguriert haben (einmalige Aufgabe), werden diese Einstellungen für alle Benutzer übernommen, die die App mit ihrem HubSpot-Account verknüpfen. Auf der Registerkarte Endpunkte finden Sie alle Details, wie Sie diese Einstellungen erstellen.

Wenn Ihre Anrufeinstellungen fertig sind, müssen Benutzer den App-Verknüpfungsprozess durchlaufen, um Ihren Calling-Dienst in ihrem HubSpot-Account verfügbar zu machen. 

Der Calling-Prozess

Bei Anrufen mithilfe von Calling-Erweiterungen gibt es die folgenden Schritte:

  1. Der Benutzer klickt auf das Anruf-Symbol in einem CRM-Datensatz.
  2. Der Benutzer wählt Ihre App als Anrufanbieter aus und klickt auf die Schaltfläche Über Browser anrufen.
  3. Ein iframe öffnet die in den Calling-Einstellungen angegebene URL in Ihrer App.
  4. Der Anruf wird über Ihre App abgeschlossen (im iframe angezeigt).
  5. HubSpot erstellt eine Platzhalter-Interaktion und sendet die ID dieser Interaktion an Ihre Spp über das SDK für Calling-Erweiterungen.
  6. Ihre App aktualisiert die Platzhalter-Interaktion mit den vollständigen Details des Anrufs.

Wenn ein Benutzer Ihre App mit HubSpot verknüpft, wird sie beim Anruf von einem Datensatz als zusätzliche Option angezeigt. Wenn Benutzer auf das Anruf-Symbol klicken, wird die Option, den Anruf mithilfe Ihrer App anstelle des standardmäßigen HubSpot-Calling-Systems vorzunehmen, angezeigt. 

Erfahren Sie mehr über das Tätigen von Anrufen in HubSpot

calling_provider

Wenn der Benutzer den Anruf über seinen Browser tätigt, öffnet ein iframe die in den Calling-Einstellungen angegebene URL in Ihrer App. Diese URL sollte auf einer benutzerdefinierte Webanwendung zeigen, die den Anruf über Ihren Calling-Dienst tätigt. Ihre App kommuniziert mithilfe des SDKs für Calling-Erweiterungen mit der HubSpot-App. Das Messages-Tool von der HubSpot-App lässt Ihre App wissen, welche Nummer angerufen werden soll. Ihre App ist in der Lage, Nachrichten für Ereignisse zu senden, wie z. B. das Ende eines Anrufs oder Benutzer, die von Ihrem Dienst abgemeldet wurden.

calling_iframe

Wenn Sie Ihre App erstellen, müssen Sie Folgendes bedenken:

  • Sie müssen eine Web-App haben, die in einem iframe angezeigt werden kann, da HubSpot keine Inhalte des iframe verarbeitet. Daher können Sie die iframe-URL nicht auf einen Backend-SIP-Dienst festlegen.
  • Die Parameter für die Höhe und Breite, die durch die Einstellungen-API festgelegt sind, bestimmen die Größe des iframe. Fenster mit einer Höhe von 600 Pixel und einer Breite von 400 Pixel sind bestens für eine Vielzahl an Browserfenstergrößen geeignet, einschließlich kleineren Bildschirmen.
  • Stellen Sie sicher, dass die Fehlerbedingungen innerhalb des iframe angezeigt werden. Die App kann Benutzer über Audioprobleme, Netzwerkprobleme oder andere Fehler informieren.

Testen

Während der Erstellung Ihrer App können Sie die iframe-URL für Ihren Browser manuell festlegen, indem Sie einen localStorage-Wert festlegen. Dadurch können Sie eine localhost-URL für lokale Tests festlegen.

Um den Wert festzulegen, öffnen Sie die Entwickler-Tools für Ihren Browser und führen Sie den folgenden JavaScript-Befehl in der Entwicklerkonsole aus:

localStorage.setItem('LocalSettings:Sales:CallingExtensions', '{"name": „Titel der Calling-Beispiel-App", "url": "https://myWidgetUrl/path/"}')

Der name-Wert wird im Header des Calling-Widgets angezeigt und url ist die URL, die für das iframe verwendet wird. Wenn dieses Element festgelegt ist, wird der von Ihnen festgelegte name als Option für den Anrufanbieter angezeigt, wenn Sie auf das Anruf-Symbol klicken und das Calling-Widget wird die von Ihnen festgelegte iframe url verwenden.

Anruf in HubSpot protokollieren

In HubSpot werden Anrufe als Interaktionsobjekte protokolliert. Diese Interaktionen werden verwendet, um die Anrufdetails in der Chronik des zugehörigen CRM-Objekts anzuzeigen. Sie werden auch für das integrierte Sales-Reporting von HubSpot verwendet.

Wenn ein Anruf über Ihre App getätigt wird, erstellt HubSpot automatisch das Basisinteraktionsobjekt und sendet die ID dieser Interaktion an Ihre App über das SDK für Calling-Erweiterungen. Die ID wird mit der onEngagementCreated-Funktion an Ihre App weitergegeben. HubSpot legt die grundlegenden Details der Interaktion, einschließlich des zuständigen Mitarbeiters, des Typs und der Zuordnungen, fest. Sie müssen die Details in den Metadaten des Interaktionsdatensatzes aktualisieren, um die Dauer des Anrufs sowie Hinweise für den Anruf im Feld body festzulegen. Wenn eine Aufzeichnung des Anrufs vorhanden ist, können Sie auch recordingUrl festlegen, die HubSpot-Benutzer wiedergeben können, wenn Sie den Kontaktdatensatz in HubSpot anzeigen.

Weitere Informationen über die Aktualisierung von Interaktionen finden Sie in unserer Dokumentation über CRM-Interaktionen.

Zum Beispiel:

// { "engagement": { "timestamp": 1561953600000 // A millisecond timestamp of the time of the call. This will default to the time that the call was initiated, but can be updated if needed. }, "metadata": { // Details for the call "toNumber": "+1 (888) 482-7768", // The number that was called. Displayed as a string, with no further formatting. "durationMilliseconds": 38000, // The length of the call in milliseconds. "recordingUrl": "https://app.example.com/Recordings/callrecordpath", // A path to a recording of the call "body": "Call notes" // Details about the call, displayed as the description } }

Die oben genannten Details würden zu einer Interaktion führen, die in HubSpot als Bild angezeigt wird:

calling-sdk-engagement

In den CRM-Interaktionen finden Sie weitere Informationen zu Interaktionen.


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.