Videokonferenz-Erweiterung

Die Videokonferenz-API bietet Integratoren die Möglichkeit, den Flow zur Meetingerstellung in HubSpot zu verknüpfen und Videokonferenz-Informationen zum Meeting hinzuzufügen. Die Verwendung dieser API umfasst folgende Schritte: 

  1. Richten Sie Ihre App mit Webhooks zu Videokonferenz-Erweiterungen ein. Sie stellen HubSpot URIs bereit, die HubSpot verwendet, um Sie zu benachrichtigen, wenn Kunden Meetings erstellen oder aktualisieren. 
  2. Verarbeiten Sie die „Meeting erstellen“-Webhooks und optional die „Meeting aktualisieren“-Webhooks. 
  3. Verarbeiten Sie Webhooks zur Verifizierung der Benutzeridentität, falls erforderlich. 

Einstellungen-API 

Entwickler verwenden diese Einstellungen-API, um eine vorhandene Anwendung einzurichten. Sie können das Zugriffstoken von Ihrer privaten App verwenden, um die Anfrage zu authentifizieren. 

 

Einstellungen-Objektdefinition 

Das Einstellungen-Objekt hat die folgenden Felder: 

createMeetingUrl: die URL, in der wir Anfragen für neue Videokonferenzen senden. https-Protokoll erforderlich. 

updateMeetingUrl: (optional) die URL, in der wir Aktualisierungen an vorhandenen Meetings senden. Wird in der Regel aufgerufen, wenn der Benutzer das Thema oder die Zeiten eines Meetings ändert. https-Protokoll erforderlich. 

deleteMeetingUrl: (optional) die URL, in der wir Sie über die in HubSpot gelöschten Meetings benachrichtigen. 

userVerifyUrl: (optional) die URL, die wir verwenden, um zu überprüfen, ob ein Benutzer in Ihrem System existiert. 

Einstellungen für die Videokonferenz-Erweiterung erstellen oder aktualisieren 

Beispielanfrage:

PUT /crm/v3/extensions/videoconferencing/settings/{appId}

JSON
//example request

{
"createMeetingUrl": "https://example.com/create-meeting",
"updateMeetingUrl": "https://example.com/update-meeting",
"deleteMeetingUrl": "https://example.com/delete-meeting"
}

Beispielantwort:

JSON
// example 200 response
{
"createMeetingUrl": "https://example.com/create-meeting",
"updateMeetingUrl": "https://example.com/update-meeting",
"deleteMeetingUrl": "https://example.com/delete-meeting"
}

Beispielantwort:

Optionale Werte sollten aus der Anfrage ausgeschlossen werden, da leere Zeichenfolgen oder andere Werte wahrscheinlich zu einem unerwünschten Verhalten führen.

Einstellungen für die Videokonferenz-Erweiterung abrufen

Beispielanfrage:

GET /crm/v3/extensions/videoconferencing/settings/{appId}

Beispiel-Antwort:

JSON
// example 200 response
{
"createMeetingUrl": "https://example.com/create-meeting",
"updateMeetingUrl": "https://example.com/update-meeting"
"deleteMeetingUrl": "https://example.com/delete-meeting"
"userVerifyUrl": "https://example.com/user-verify"
}

„Meeting erstellen“-Webhook

Wenn ein Meeting erstellt wird, sendet HubSpot eine Anfrage an createMeetingUri

Beispielanfrage:

JSON
// example request
{
"portalId": 123123,
"userId": 123,
"userEmail": "test.user@example.com",
"topic": "A Test Meeting",
"source": "MEETINGS"
"startTime": 1534197600000,
"endTime": 1534201200000
}

Die Felder in dieser Anfrage sind:

  • portalId: die ID des HubSpot-Accounts (als Portal bezeichnet).
  • userId: die eindeutige ID für den HubSpot-Benutzer, der das Meeting moderiert.
  • userEmail: die E-Mail-Adresse des HubSpot-Benutzers, der das Meeting moderiert.
  • topic: das Thema bzw. der Titel des Meetings.
  • source: entweder MEETINGS oder MANUAL, verweist auf die Meeting-Funktion innerhalb
    der HubSpot-App, in der das Meeting erstellt wurde; MEETING entspricht
    der „Meetinlink“-Funktion, MANUAL entspricht einem Meeting,
    das in der CRM-Kommunikation erstellt wurde.
  • startTime: die Startzeit des Meetings (in Epoche-Millisekunden)
  • endTime: die Endzeit des Meetings (in Epoche-Millisekunden)

Um diesen Webhook erfolgreich zu verarbeiten, sollte der Entwickler eine Videokonferenz für dieses Meeting erstellen (oder es mit einer bestehenden Konferenz verlinken) und mit Informationen zu dieser Konferenz antworten.


Beispiel-Antwort:

JSON
//example response
{
"conferenceId": "some-unique-id",
"conferenceUrl": "https://example.com/join",
"conferenceDetails": "Click here to join: https://example.com/join"
}

Die in dieser Antwort erwarteten Felder sind:

  • conferenceId: eine eindeutige ID, die der Konferenz in diesem Ereignis zugeordnet ist.
    Diese ID muss in Ihrem gesamten System eindeutig sein. Wir geben diese ID
    im Aktualisieren-Webhook an Sie zurück.
  • conferenceUrl: der Join-Link für die erstellte Konferenz. Dieser kann
    im Feld „location“ der Ereignisse platziert werden.
  • conferenceDetails: Informationen zu „invitation“, nur Text. Sollte beschreiben,
    wie Teilnehmer des Ereignisses auf die Videokonferenz
    für dieses Ereignis zugreifen können. Neue Zeilen werden in Darstellungen dieses Texts in unser
    System gepflegt. Es werden jedoch keine anderen Formatierungen unterstützt.

„Meeting aktualisieren“-Webhook

Wenn Sie updateMeetingUri spezifiziert haben, sendet HubSpot dieser URI immer dann ein Anfrage, wenn sich meetingrelevante Details geändert haben. Diese Benachrichtigung ist notwendig, wenn Sie das aktuelle Thema oder die aktuellen Zeiten für eine Videokonferenz pflegen müssen.


Beispielanfrage:

JSON
//example request
{
"conferenceId": "some-unique-id",
"userId": 123,
"userEmail": "test.user@example.com",
"portalId": 123123,
"topic": "A Test Meeting (updated)",
"startTime": 1534197600000,
"endTime": 1534201200000
}

Die in dieser Antwort erwarteten Felder sind:

  • conferenceId: die eindeutige ID für die Konferenz, die von Ihrer Integration in der Antwort auf den „Meeting erstellen“-Webhook bereitgestellt wird.
  • userId: die eindeutige ID für den HubSpot-Benutzer, der das Meeting moderiert. Dies ist immer die gleiche userId wie die Anfrage zur Erstellung von Meetings.
  • userEmail: die E-Mail-Adresse des HubSpot-Benutzers, der das Meeting moderiert. Dies ist immer die gleiche userEmail wie die Anfrage zur Erstellung von Meetings.
  • topic: das Thema bzw. der Titel des Meetings.
  • startTime: die Startzeit des Meetings (in Epoche-Millisekunden)

endTime: die Endzeit des Meetings (in Epoche-Millisekunden)

Wenn Sie auf diese Anfragen antworten, ist ein „No response“-Text erforderlich. Wir erfordern nur
einen 200- oder 204-Antwortcode, um uns zu informieren, dass dieser Webhook
erfolgreich empfangen wurde.

„Meeting löschen“-Webhook

Wenn ein Meeting in HubSpot gelöscht wird, sendet HubSpot eine Anfrage an deleteMeetingUri.
Beispielanfrage:

JSON
//example request
{
"conferenceId": "some-unique-id"
}

Diese Anfrage enthält nur die conferenceId des Meetings, das gelöscht wurde.
Wenn Sie auf diese Anfragen antworten, ist ein „No response“-Text erforderlich. Wir erfordern nur
einen 200- oder 204-Antwortcode, um uns zu informieren, dass dieser Webhook
erfolgreich empfangen wurde.

„Benutzer verifizieren“-Webhook

Die Systeme von HubSpot kommunizieren ständig Informationen über die Benutzer, z. B. die HubSpot-ID und die E-Mail-Adresse des HubSpot-Accounts. Es besteht die Möglichkeit, dass ein Benutzer im System von HubSpot in Ihrem System mit einer anderen E-Mail-Adresse oder einer anderen ID vorhanden ist.

Bevor wir einen Aufruf für Ihr System starten, um einen Web-Konferenz-Link zu erstellen, zu aktualisieren oder zu löschen, werden zunächst Ihre userVerifyUri-Einstellungen überprüft. Wenn diese URI festgelegt wurde, starten wir einen Aufruf, um Ihre native Benutzer-ID abzurufen. Anschließend senden wir diese ID als E-Mail-Adresse des Benutzers im
nachfolgenden Aufruf.

Es gibt Orte in der HubSpot-App, an denen wir mit diesem Aufruf überprüfen können, ob der Benutzer in Ihrem System vorhanden ist, bevor wir die UI-Komponenten anzeigen, mit denen dieser interagieren kann. Es ist eine Art Vorüberprüfung. Wenn Sie diese URI nicht konfigurieren, gehen wir immer davon aus, dass die Identität des Benutzers verifiziert ist.

Es ist Ihre Entscheidung, ob Sie diese Funktion unterstützen. Wenn Sie eine Benutzerzuordnung in Ihrem System beibehalten möchten, können Sie möglicherweise die HubSpot-Benutzer-ID oder E-Mail an Ihre interne Benutzer-ID in jedem Aufruf zuordnen.


Die Anfrage sieht wie folgt aus:

JSON
//example request
{
"portalId": 123123,
"userEmail": "test.user@example.com"
}

Sie können einen 200- oder einen beliebigen Fehlercode (z. B. 404) zurückgeben. Bei einem 200-Fehlercode sollten Sie eine Payload mit der neuen ID zurückgeben, die wir anstelle von „email“ verwenden sollen:

JSON
//example response
{
"id": "any-string-id"
}

Webhook-Signatur

Alle Webhooks, die von HubSpot gesendet wurden, sind mit HMAC unter Verwendung Ihres „App-Geheimnisses“ signiert. Weitere Informationen finden Sie auch im Abschnitt „Sicherheit“ auf dieser Seite: (Der Rest dieser Webhook-Übersichtsseite gilt nicht für Webhooks für diese Videokonferenz-Erweiterung.)


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.