Envoyer des occurrences d'événements (BÊTA)

Après avoir défini un schéma de type d’événement et récupéré son fullyQualifiedName, vous pouvez envoyer des données d’occurrence d’événement via l’API d’événements de l’application. Lors de l’envoi de données d’événement, vous devrez respecter le schéma que vous avez créé précédemment. Les requêtes qui ne correspondent pas au schéma échoueront à être validées et ne seront pas capturées par l’application.

Envoi d’occurrence d’événements

Envoyer une occurrence unique
Envoyer un lot d'occurrences

Pour envoyer une occurrence d’événement unique, effectuez une requête POST à /integrators/timeline/v4/events.Dans le corps de la requête, incluez les données d’événements suivant le schéma défini pour le type d’événement ainsi que la valeur fullyQualifiedName dans un champ eventTypeName.

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

Pour envoyer un lot d’occurrences d’événements, effectuez une demande POST à /integrators/timeline/v4/events/batch.Dans le corps de la requête, incluez jusqu’à 500 objets d’occurrence d’événement séparés par des virgules dans un tableau inputs. Si certaines occurrences ne sont pas validées, les occurrences validées avec succès seront toujours acceptées et persistées.

{
  "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": {}
    }
  ]
}

Les champs marqués par * sont requis.

Champ	Type	Description
`eventTypeName`*	Chaîne	le nom entièrement qualifié du type d’événement, que vous utiliserez pour identifier l’événement via l’API. Cette valeur est automatiquement définie par HubSpot et peut être obtenue via l’API après la création du type d’événement. Cette valeur ne peut pas être modifiée après la création.
`objectId`*	Chaîne	l’ID de la fiche d’informations de CRM à associer à l’événement. Ce champ peut être utilisé pour tous les types de fiches d’informations de CRM et constitue l’identifiant recommandé. Découvrez-en davantage sur l’association des fiches d’informations CRM.
`email`	Chaîne	pour l’association de contact, vous pouvez fournir l’adresse e-mail du contact à associer. Découvrez-en davantage sur l’association des fiches d’informations CRM.
`utk`	Chaîne	pour l’association de contacts, vous pouvez fournir le jeton utilisateur d’un contact existant à associer. Découvrez-en davantage sur l’association des fiches d’informations CRM.
`domain`	Chaîne	incluez ce champ en plus de `objectId` pour définir la valeur de propriété de l’entreprise `domain`. Découvrez-en davantage sur l’association des fiches d’informations CRM.
`timestamp`	Chaîne	définit l’heure de l’occurrence de l’événement (format ISO 8601). Si ce champ n’est pas renseigné, HubSpot utilisera par défaut l’horodatage de l’envoi des données d’occurrence d’événement.
`properties`	Objet	paires clé-valeur des noms et valeurs des propriétés que vous avez configuré pour le type d’événement. Découvrez-en davantage sur les propriétés d’événement.
`extraData`	Objet	des informations supplémentaires qui seront disponibles pour les modèles de rendu de chronologie. Doit être au format JSON valide.
`timelineIFrame`	Objet	une fois incluse, la carte de chronologie comprendra un lien hypertexte qui permet aux utilisateurs d’ouvrir le contenu lié dans un iframe. Découvrez-en davantage sur l’utilisation des iframes.
`id`	Chaîne	un identifiant unique pour l’occurrence de l’événement. Doit être unique dans le type d’événement. Si ce champ n’est pas renseigné, HubSpot générera un GUID aléatoire. Lorsque plusieurs événements ont le même ID, le premier sera accepté et tous les autres seront rejetés.

Association des fiches d’informations CRM

Chaque événement doit être associé à une fiche d’informations CRM, le type d’objet CRM étant défini par le schéma de type d’événement. L’API des événements de l’application comprend plusieurs champs pour associer les données d’occurrence d’événement aux fiches d’informations CRM. Pour tous les objets CRM pris en charge, il est recommandé d’utiliser le champ objectId. Cependant, dans certaines situations, vous souhaiterez peut-être utiliser les autres champs.

utk/email : si vous ne connaissez pas l’ID du contact, utilisez le champ utk et/ou email pour l’identification. Fournir ces deux identifiants vous permet également de créer et de mettre à jour des contacts. Par exemple :
- Si utk correspond à un contact existant, mais que l’email ne correspond pas, HubSpot mettra à jour le contact (par utk) avec la nouvelle adresse e-mail.
- Si aucun objectId n’est fourni, l’occurrence de l’événement sera associée à un contact existant correspondant à utk/email, ou HubSpot créera un nouveau contact si aucune correspondance n’est trouvée.
- Notez que le utk seul ne peut pas créer de nouveaux contacts. Vous devez toujours inclure l’email avec utk pour garantir une bonne association.
domain : pour l’association d’entreprises, vous devez fournir l’objectId, mais vous pouvez également l’inclure le domain pour mettre à jour la propriété de domain de cette entreprise.

Voici l’ordre de priorité des propriétés d’association des fiches d’informations CRM, le nombre le plus bas étant la priorité la plus élevée :

Champ	Priorité	Description
`objectId`	1	L’ID de fiche d’informations CRM (recommandé).
`utk`	2	Le jeton d’utilisateur du contact (contacts uniquement).
`email`	3	L’adresse e-mail du contact (contacts uniquement).
`domain`	4	Le domaine de l’entreprise (entreprises uniquement).

Envoi de données supplémentaires

Au-delà de l’envoi de données aux propriétés d’événement et de la mise à jour des propriétés CRM via les occurrences d’événement, vous pouvez inclure des données supplémentaires pour le rendu de la chronologie via l’objet extraData.

L’objet extraData peut seulement contenir un JSON valide. Si le JSON est erroné, l’occurrence sera rejetée et vous recevrez une réponse d’erreur.

Les valeurs des champs extraData sont accessibles selon le type d’événement detailTemplate utilisant la syntaxe {{extraData.fieldName}}. Tous les niveaux d’attribut de extraData sont disponibles par le biais de la notation par points, comme {{extraData.person1.preferredName}}. Par exemple, les modèles ci-dessous utilisent les données de propriété customerName et loginLocation, ainsi que le champ surveyData de extraData envoyé via l’occurrence d’événement. Capture d'écran montrant l'exemple de modèle de rendu ci-dessous sur la chronologie d'un contact.

Capture d'écran montrant l'exemple de modèle de rendu ci-dessous sur la chronologie d'un contact.

Données sur l'occurrence d'événements
Configuration du modèle de chronologie

{
  "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}}",

Créer des applications

Ajouter des fonctionnalités

Publier dans la Marketplace HubSpot

Envoyer des occurrences d'événements (BÊTA)

Envoi d’occurrence d’événements

Association des fiches d’informations CRM

Envoi de données supplémentaires

​Envoi d’occurrence d’événements

​Association des fiches d’informations CRM

​Envoi de données supplémentaires

Envoi d’occurrence d’événements

Association des fiches d’informations CRM

Envoi de données supplémentaires