Senden von Event-Vorkommnissen (BETA)

Nachdem Sie ein Event-Typschema definiert und dessen fullyQualifiedNameabgerufen haben, können Sie Daten zum Auftreten von Events über die App-Events-API senden. Beim Senden von Event-Daten müssen Sie sich an das zuvor erstellte Schema halten. Anfragen, die nicht mit dem Schema übereinstimmen, schlagen bei der Validierung fehl und werden nicht von der App erfasst.

Senden von Event-Occurrences

Ein einzelnes Vorkommnis senden
Vorkommnisse gebündelt senden

Um ein einzelnes Event-Vorkommnis zu senden, stellen Sie eine POST-Anfrage an /integrators/timeline/v4/events.Fügen Sie im Anfragetext Ereignisdaten hinzu, die dem definierten Schema des Event-Typs folgen, zusammen mit dem fullyQualifiedName-Wert in einem eventTypeName-Feld.

{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},

Um einen Batch von Event-Vorkommnissen zu senden, stellen Sie eine POST-Anfrage an /integrators/timeline/v4/events/batch.Fügen Sie im Anfragetext bis zu 500 durch Kommata getrennte Event-Vorkommnisobjekte in einem inputs-Array ein. Wenn Vorkommnisse nicht validiert werden können, werden erfolgreich validierte Vorkommnisse weiterhin akzeptiert und beibehalten.

{
  "inputs": [
    {
      "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_100",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "mobileApp"
      },
      "extraData": {
        "surveyData": [
          {
            "question": "How was your login experience?",
            "answer": "Fine!"
          },
          {
            "question": "How likely are you to recommend logging in to a co-worker?",
            "answer": "Extremely likely"
          }
        ]
      }
    },
    {
      "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_101",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "website"
      },
      "extraData": {}
    }
  ]
}

Mit * markierte Felder sind Pflichtfelder.

Feld	Typ	Beschreibung
`eventTypeName`*	Zeichenfolge	Der vollständig qualifizierte Name des Event-Typs, den Sie verwenden, um das Event über die API zu identifizieren. Dieser Wert wird von HubSpot automatisch festgelegt und lässt sich nach der Erstellung des Event-Typs über die API abrufen. Dieser Wert kann nach der Erstellung nicht mehr geändert werden.
`objectId`*	Zeichenfolge	Die ID des CRM-Datensatzes, der dem Auftreten des Events zugeordnet werden soll. Dieses Feld kann für alle Arten von CRM-Datensätzen verwendet werden und ist die empfohlene ID. Erfahren Sie mehr über CRM Datensatzzuordnung.
`email`	Zeichenfolge	Für die Kontakt-Zuordnung können Sie die E-Mail-Adresse des zuzuordnenden Kontakts angeben. Erfahren Sie mehr über CRM-Datensatzzuordnung.
`utk`	Zeichenfolge	Für die Kontaktzuordnung können Sie das Benutzer-Token eines vorhandenen Kontakts angeben, der zugeordnet werden soll. Erfahren Sie mehr über CRM-Datensatzzuordnung.
`domain`	Zeichenfolge	Fügen Sie dieses Feld zusätzlich zu `objectId` hinzu, um den `domain`-Eigenschaftswert des Unternehmens festzulegen. Erfahren Sie mehr über CRM-Datensatzzuordnung.
`timestamp`	Zeichenfolge	Legt den Zeitpunkt des Auftretens des Events fest (ISO 8601-Format). Wenn nichts angegeben wird, verwendet HubSpot standardmäßig den Zeitstempel, an dem die Daten des Event-Vorkommnisses gesendet werden.
`properties`	Objekt	Schlüsselwert-Paare von Eigenschaftsnamen und Eigenschaftswerte, die Sie für den Event-Typ konfiguriert haben. Erfahren Sie mehr über Event-Eigenschaften.
`extraData`	Objekt	Zusätzliche Informationen, die für Chronik-Rendering-Vorlagen verfügbar sind. Muss im gültigen JSON-Format vorliegen.
`timelineIFrame`	Objekt	Wenn dies verwendet wird, enthält die Chronik-Karte einen Hyperlink, der es Benutzern ermöglicht, die verlinkten Inhalte in einem iframe zu öffnen. Erfahren Sie mehr über die Verwendung von iframes.
`id`	Zeichenfolge	Eine eindeutige ID für das jeweilige Event-Vorkommnis. Muss innerhalb des Event-Typs eindeutig sein. Falls nicht anders angegeben, generiert HubSpot eine zufällige UUID. Wenn mehrere Events die gleiche ID haben, wird die erste akzeptiert und alle anderen abgelehnt.

Zuordnung von Datensätzen

Jedes Auftreten eines Events muss einem CRM-Datensatz zugeordnet werden, wobei der CRM-Objekttyp durch das Event-Typschema definiert ist. Die App-Events-API enthält mehrere Felder, mit denen sich Daten von Event-Vorkommnissen CRM-Datensätzen zuordnen lassen. Für alle unterstützten CRM-Objekte wird empfohlen, das objectId-Feld zu verwenden. Es gibt jedoch einige Situationen, in denen Sie vielleicht andere Felder bevorzugen.

utk/email: Wenn Sie die ID des Kontakts nicht kennen, verwenden Sie das utk-Feld und/oder email-Feld zur Identifizierung. Die Angabe dieser beiden IDs ermöglicht es Ihnen auch, Kontakte zu erstellen und zu aktualisieren. Zum Beispiel:
- Wenn utk mit einem vorhandenen Kontakt übereinstimmt, jedoch email nicht, aktualisiert HubSpot den Kontakt (gemäß utk) mit der neuen E-Mail-Adresse.
- Ist kein objectId angegeben, wird das Auftreten des Events einem vorhandenen Kontakt zugeordnet, der mit utk/email übereinstimmt, oder HubSpot erstellt einen neuen Kontakt, wenn keine Übereinstimmung vorliegt.
- Beachten Sie bitte, dass anhand von utk allein kein neuer Kontakt erstellt werden kann. Sie sollten immer email zusammen mit utk erwähnen, um eine ordnungsgemäße Zuordnung zu gewährleisten.
domain: Für Unternehmenszuordnungen müssen Sie das objectId angeben, können aber auch domain einschließen, um die domain-Eigenschaft dieses Unternehmens zu aktualisieren.

Nachfolgend finden Sie die Prioritätenfolge für die Eigenschaftszuordnung von CRM-Datensätzen, wobei die kleinste Zahl die höchste Priorität darstellt:

Beschreibung der Feldpriorität
`objectId`	1	Die CRM-Datensatz-ID (empfohlen)
`utk`	2	Das Kontaktbenutzertoken (nur Kontakte)
`email`	3	Die E-Mail-Adresse des Kontakts (nur Kontakte)
`domain`	4	Die Unternehmen Domain (nur Unternehmen)

Zusätzliche Daten senden

Neben dem Senden von Daten an Event-Eigenschaften und dem Aktualisieren von CRM-Eigenschaften über das Auftreten von Events können Sie zusätzliche Daten für das Chronik-Rendering per extraData-Objekt einbeziehen.

Das extraData-Objekt darf nur gültige JSON-Dateien enthalten. Wenn diese falsch formatiert sind, wird das Event-Vorkommnis abgelehnt und Sie erhalten eine Fehlerantwort.

Auf extraData-Feldwerte kann über die detailTemplate des Eventtyps unter Verwendung der {{extraData.fieldName}}-Syntax zugegriffen werden. Alle Attributebenen von extraData sind durch Punktnotation verfügbar, z. B {{extraData.person1.preferredName}}. Die folgenden Vorlagen verwenden beispielsweise die customerName- und loginLocation-Eigenschaftsdaten zusammen mit dem surveyData-Feld von extraData, was über das Event-Vorkommnis gesendet wurde. Screenshot, der zeigt, wie das folgende Beispiel einer Rendering-Vorlage auf der Kontaktchronik erscheint.

Screenshot, der zeigt, wie das folgende Beispiel einer Rendering-Vorlage auf der Kontaktchronik erscheint.

Daten zum Event-Vorkommnis
Konfiguration der Chronikvorlage

{
  "eventTemplateId": "5488733",
  "objectId": "769851",
  "tokens": {
    "customerName": "Tim",
    "loginLocation": "mobileApp"
  },
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer": "Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer": "Extremely likely"
      }
    ]
  }
}

"headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",

Integrationen erstellen

Funktionen hinzufügen

Im HubSpot Marketplace veröffentlichen

Senden von Event-Vorkommnissen (BETA)

Senden von Event-Occurrences

Zuordnung von Datensätzen

Zusätzliche Daten senden

​Senden von Event-Occurrences

​Zuordnung von Datensätzen

​Zusätzliche Daten senden

Senden von Event-Occurrences

Zuordnung von Datensätzen

Zusätzliche Daten senden