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.

• Anforderungen an den Bereich
• Event-Teilnahme-Endpunkte
• App-Einstellungen konfigurieren
  • Schritt 1: Eine API in Ihrer App erstellen
  • Schritt 2: HubSpot den URL-Pfad zu Ihrer API bereitstellen

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.

Sie können Marketingevents erstellen oder aktualisieren, indem Sie eine POST-Anfrage an den /marketing/v3/marketing-events/events/upsert-Endpunkt durchführen. Sie können alle customProperties, die den Events entsprechen, die Sie aktualisieren möchten, zusammen mit allen anderen Details Ihres Events (einschließlich Name, Startzeit und Beschreibung) im inputs-Feld Ihres Anfragetextes berücksichtigen.

Wenn bereits ein Marketingevent mit der angegebenen ID in Ihrer Anfrage vorhanden ist, wird es aktualisiert. Andernfalls wird ein neues Event erstellt.

Zum Beispiel würde die folgende Anfrage ein Event mit einer ID von 4 mit dem Namen „Virtueller Kochkurs“ erstellen:

Sie können eine vollständige Liste aller verfügbaren Felder überprüfen, die Sie in Ihre Anfrage aufnehmen können, indem Sie oben in diesem Artikel auf die Registerkarte Endpunkte klicken.

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. 

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.

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:

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.

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