Marketingevents

„Marketingevents“ ist ein CRM-Objekt, ähnlich wie Kontakte und Unternehmen, mit dem Sie Marketingevents wie ein Webinar nachverfolgen und anderen HubSpot CRM-Objekten zuordnen können. Im Folgenden erfahren Sie mehr über die Zusammenarbeit mit der Marketingevent-API, um Marketingevents in eine App zu integrieren.

In this article

Anforderungen an den Bereich

Um eine API-Anfrage an einen der Marketingevent-Endpunkte durchzuführen, sind die folgenden Bereiche erforderlich:

  • crm.objects.marketing_events.read: Erteilt die Berechtigung zum Abrufen von Marketingevent- und -Teilnahmedaten.
  • crm.objects.marketing_events.write Wenn Sie Marketingevent-Informationen erstellen, löschen oder ändern möchten.

Wenn Sie von Ihrer App durchgeführte Aufrufe authentifizieren, können Sie entweder dasZugriffstoken einer privaten App oder OAuth verwenden. Erfahren Sie mehr über Authentifizierungsmethoden. Für die vollständige Liste der verfügbaren Endpunkte klicken Sie oben in diesem Artikel auf die Registerkarte „Endpunkte“.

Event-Teilnahme-Endpunkte

Die Event-Teilnahmestatus-Endpunkte ermöglichen es Ihnen, einen Abonnementstatus zwischen einem HubSpot-Kontakt und einem Marketingevent zu protokollieren. Sie können beispielsweise diesen Endpunkt verwenden, um zu protokollieren, dass sich ein HubSpot-Kontakt für ein Marketingevent registriert hat.

Es gibt zwei Endpunkte, die Sie verwenden können, um den Teilnahmestatus eines Kontakts zu aktualisieren. Wenn Sie zuvor die Endpunkte /upsert oder/email-upsert verwendet haben, um den Status eines Teilnehmers zu aktualisieren, können Sie stattdessen die unten aufgeführten Endpunkte verwenden, um die gleiche Funktionalität beizubehalten und gleichzeitig die Teilnahmedauer des Kontakts in der Kontaktchronik auszufüllen:

  • Wenn Sie die Kontakt-IDs von bestehenden Kontakten verwenden möchten:
    • Führen Sie eine POST -Anfrage an /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/create durch, indem Sie die ID des Events aus Ihrer externen Anwendung als externalEventId verwenden.
    • Geben Sie im Anforderungstext ein inputs-Objekt an, das die folgenden Felder enthält:
      • interactionDateTime: Datum und Uhrzeit, zu dem Kontakt das Event abonniert hat.
      • vid: die Kontakt-ID eines vorhandenen Kontakts.
  • Wenn Sie die E-Mail-Adresse eines der Teilnehmer der Veranstaltung verwenden möchten:
    • Führen Sie eine POST-Anfrage an /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/email-create durch.
    • Geben Sie im Anforderungstext ein inputs-Objekt an, das die folgenden Felder enthält:
      • interactionDateTime: Datum und Uhrzeit, zu dem Kontakt das Event abonniert hat.
      • email: die E-Mail-Adresse des Teilnehmers als Wert des E-Mail-Felds in einer Eingabe. 
    • Stimmt die von Ihnen angegebene E-Mail-Adresse nicht mit der Adresse eines vorhandenen Kontakts überein, wird ein neuer Kontakt erstellt.

Geben Sie für beide oben genannten Endpunkte die folgenden Werte für die entsprechenden Pfadparameter an:

  • externalEventId: die ID des Marketingevents.
  •  subscriberState: eine Enumeration, die dem neuen Teilnehmerstatus des Kontakts entspricht:
    • REGISTERED: Gibt an, dass sich der HubSpot-Kontakt für das Event registriert hat.
    • ATTENDED: Gibt an, dass der HubSpot-Kontakt am Event teilgenommen hat. Wenn Sie den Status eines Kontakts auf ATTENDED aktualisieren, können Sie auch die Zeitstempel joinedAt und leftAt als Parameter in den Anfragetext einfügen, der im ISO8601 Instant-Format angegeben ist.
    • CANCELLED: Gibt an, dass der HubSpot-Kontakt, der sich zuvor für das Event registriert hatte, seine Registrierung storniert hat.

Sobald Ihr Event abgeschlossen ist, können Sie es als abgeschlossen markieren und die Teilnehmerkennzahlen (z. B. die Dauer der Teilnahme für alle Teilnehmer) berechnen, indem Sie eine POST-Anfrage an /marketing/v3/marketing-events/events/{externalEventId}/complete durchführen. Beachten Sie, dass diese Aktion nicht rückgängig gemacht werden kann. Daher sollten Sie diesen Endpunkt erst aufrufen, wenn alle Änderungsevents bezüglich des Teilnehmerstatus bereits erfolgt sind. 

Please note: these APIs are idempotent so long as the ID of the contact and the interactionDateTime value in the event has not changed. This enables you to safely set subscriber state multiple times without HubSpot creating duplicate events in the marketing events properties.

App-Einstellungen konfigurieren

Es ist ein gewisses Setup erforderlich, damit Marketingevents ordnungsgemäß mit HubSpot synchronisiert werden können.

Wenn Sie HubSpot eine Änderung des Abonnentenstatus übermitteln (z. B. eine Registrierung oder ein storniertes Event), prüft HubSpot zunächst, ob ein Marketingevent für die angegebene Event-ID vorhanden ist. Ist dies nicht der Fall, ruft HubSpot den konfigurierten Endpunkt für Ihre App auf, um die Details des Marketingevents abzurufen, erstellt dann das Event in HubSpot und veröffentlicht die Änderung des Abonnentenstatus.

Dies geschieht, um Ihnen die Arbeit zu erleichtern. Es wird jedoch weiterhin empfohlen, die Marketingevents selbst über die auf der Registerkarte „Endpunkte“ oben in diesem Artikel angegebenen CRUD-Methoden zu erstellen und sich nicht auf diese Funktionalität zu verlassen, um Ihre Marketingevents in HubSpot zu erstellen.

Schritt 1: Eine API in Ihrer App erstellen

Um dies zu unterstützen, verlangt HubSpot, dass jede App, die Marketingevents verwendet, eine API definiert, um Informationen zu einem bestimmtem Marketingevent abzurufen.

Anforderungen:

  • Akzeptiert:
    • externalAccountId: ein Abfrageparameter, der die accountId des Kunden in der externen App angibt.
    • appId: ein Abfrageparameter, der die ID der HubSpot-Anwendung angibt, die die Event-Details anfordert. Dies ist dann die ID Ihrer App.
    • externalEventId: ein Pfadparameter in der URL der Anfrage, der die ID des Events in der externen App angibt, zu dem HubSpot Details benötigt.
  • Gibt zurück:
    • Ein JSON-Objekt, das Details für das Marketingevent bereitstellt und die folgenden Felder enthält, die in der folgenden Tabelle aufgeführt sind:
Feldname Erforderlich Typ Feldbeschreibung
eventName true Zeichenfolge Der Name des Marketingevents
eventOrganizer true Zeichenfolge Der Name des Organisators des Marketingevents
eventType false Zeichenfolge Beschreibt, um welchen Typ von Event es sich handelt. Zum Beispiel: WEBINAR, CONFERENCE, WORKSHOP
startDateTime false string($date-time) Das Startdatum und die Startuhrzeit des Marketingevents.
endDateTime false string($date-time) Das Enddatum und die Enduhrzeit des Marketingevents.
eventDescription false Zeichenfolge Die Beschreibung des Marketingevents.
eventUrl false Zeichenfolge Eine URL in der externen Event-Anwendung, in der das Marketingevent stattfindet.
eventCancelled false bool Gibt an, ob das Marketingevent storniert wurde. Die Standardeinstellung ist false

HubSpot sendet auch einenX-HubSpot-Signature-v3-Header, mit dem Sie überprüfen können, ob die Anfrage von HubSpot stammt. Erfahren Sie mehr über Anfragesignaturen, um weitere Informationen zur Signatur zu erhalten und wie Sie diese validieren.

Schritt 2: HubSpot den URL-Pfad zu Ihrer API bereitstellen

Nachdem Sie nun die API in Ihrer App erstellt haben, die ein Objekt zurückgibt, das die Details eines bestimmten Marketingevents enthält, müssen Sie HubSpot den URL-Pfad zu Ihrer API bereitstellen, indem Sie eine POST-Anfrage an /marketing/v3/marketing-events/{appId}/settings durchführen. Auf diese Weise kann HubSpot ermitteln, wie Anfragen an Ihre App gestellt werden müssen, um die Details eines Marketingevents abzurufen.

Geben Sie im Text Ihrer POST-Anfrage über das Feld eventDetailsURL Ihre URL an. Die eventDetailsURL muss die folgenden beiden Voraussetzungen erfüllen:

  • Sie enthält eine %s-Zeichensequenz enthalten, die HubSpot zum Ersetzen in der ID des Events (externalEventId) als Pfadparameter verwendet.
  • Es muss der vollständige Pfad zur API-Ressource sein, einschließlich des Präfixes https:// und des Domain-Namens (z. B. my.event.app).

Wenn Sie beispielsweise eine  eventDetailsURL von https://my.event.app/events/%s konfigurieren und eine Anfrage zum Abrufen von Details eines Events mit der ID 1234-event-XYZ durchführen müssen, führt HubSpot für die HubSpot-App mit der ID app-101 und den Account mit der ID ABC-account-789 eine GET-Anfrage durch:

https://my.event.app/events/1234-event-XYZ?appId=app-101&externalAccountId=ABC-account-789


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.