Chronologie
API du CRM | Événements de chronologie
Découvrez une vue d’ensemble et une explication de l’API Chronologie.
Dernière modification : 22 août 2025
Run in Postman
Créer un modèle d’événement
Avant de commencer à créer des événements, vous devez créer un modèle d’événement. Les modèles d’événement décrivent les actions que votre application ajoutera à la chronologie d’un contact, d’une entreprise ou d’une transaction dans HubSpot. Ces actions comprennent la consultation d’une vidéo, l’inscription à un webinar ou encore la réponse à une enquête. Une seule application peut créer jusqu’à 750 modèles d’événement. Les modèles d’événement sont créés pour les contacts par défaut, mais ils peuvent être créés pour des entreprises ou des transactions via le champobjectType. Consultez la création d’un modèle d’événement de chronologie pour plus de détails.
Chaque modèle d’événement possède ses propres jetons et modèles. Vous pouvez utiliser des événements créés pour les contacts comme critères lors de la création de nouvelles listes de contacts ou de workflows, comme : « Créer une liste de tous les contacts avec une mention J’aime pour une vidéo, où le nom de la vidéo contient XYZ, où votre modèle d’événement est intitulé « Mention J’aime pour la vidéo » et possède un jeton d’événement intitulé « nom de la vidéo ».”
Créer des modèles d’événement via l’API
Dans cet exemple, un nouveau modèle d’événement, « Exemple d’inscription au webinar », sera créé. Pour l’authentification, utilisez la clé d’API de développeur trouvée dans votre compte de développeur d’applications.<appId> par votre propre ID d’application, disponible sur les pages Mes applications et Détails de l’application de votre compte de développeur. Vous devrez également remplacer <developerHapikey> par votre propre clé d’API de développeur, disponible en accédant à Applications > Obtenir la clé d’API HubSpot.
Les propriétés headerTemplate et detailTemplate peuvent également être renseignées ici Pour plus d’informations, consultez Définir des modèles d’en-tête et de détails ci-dessous.
Cette requête POST renvoie la définition complète du modèle d’événement enregistré. Veillez à noter la propriété id dans cette réponse. Il s’agit de l’ID du modèle d’événement, que vous devrez mettre à jour ainsi que les jetons à l’avenir.
Vous pouvez voir tous les modèles d’événement définis pour une application via cette commande GET, qui retournera également les ID de modèle d’événement :
Créer des modèles d’événement dans HubSpot
Outre l’utilisation de l’API pour créer et gérer des modèles d’événement de chronologie, vous pouvez également gérer les modèles d’événements dans votre compte de développeur HubSpot. Dans les paramètres de votre application, accédez à Événements de chronologie et utilisez le bouton Créer un type d’événement pour créer un nouveau modèle d’événement pour cette application. Si vous avez créé des modèles d’événement auparavant, vous les verrez ici.
Remarque :
Si vous supprimez un modèle, les événements existants utilisant ce modèle seront définitivement supprimés des comptes sur lesquels est installée votre application. Vous ne pourrez plus créer de nouveaux événements de ce type, mais vous verrez les données d’anciens événements dans les listes et les rapports. L’application de ces modifications dans HubSpot peut prendre plusieurs heures.Définir des jetons d’événement
Une fois que vous avez défini un modèle d’événement, vous souhaiterez peut-être définir ses jetons. Les jetons de modèles d’événement vous permettent de joindre des données personnalisées aux événements qui peuvent être affichées dans la chronologie et utilisées pour l’automatisation dans les workflows. Dans le cas des contacts, ils peuvent également être utilisés pour la segmentation de listes. Vous pouvez créer jusqu’à 500 jetons par modèle d’événement de chronologie.Créer des jetons d’événement via l’API
En utilisant l’ID du modèle d’événement créé à l’étape 1, des jetons seront ajoutés pour identifier les webinars auxquels les contacts se sont inscrits.GET renverra tous les jetons définis sur un modèle d’événement :
stringnumberenumeration— Un ensemble d’options. Voir l’exemple de webinarType ci-dessous.date— Toutes les dates doivent être en millisecondes selon Unix.
Définir des modèles d’en-tête et de détails
Les modèles d’en-tête et de détails définissent l’affichage d’un événement de chronologie. Vous pouvez spécifier les documents Markdown avec les modèles Handlebars. Le modèle d’en-tête doit être une description d’une ligne de l’événement et le modèle de détails est la vue d’exploration de l’événement (exemples ci-dessous). Les jetons d’événement sont transmis en tant que données aux modèles. En utilisant cet exemple, vous pouvez mentionner le jetonwebinarName dans le modèle en utilisant {{webinarName}}
Le code extraData d’un événement (voir « Comprendre extraData”ci-dessous) peut être mentionné dans le modèle de détails.
Définir des modèles d’en-tête et de détails via l’API
Les modèles d’en-tête et de détails peuvent être définis sur le modèle d’événement via les points de terminaison des modèles d’événement. Par exemple, il est possible d’ajouter des modèles à « Exemple d’inscription au webinar » en modifiant cela avecPUT :
#formatDate, définie pour permettre un format de date convivial.
Une fois que l’événement est créé pour un contact à l’aide de cela (voir “Création d’un événement” ci-dessous), voici ce qui apparaît dans la chronologie du contact :
Définir tous les aspects d’un modèle d’événement dans un seul appel
Maintenant que vous avez vu chaque aspect d’un modèle d’événement, vous pouvez tous les définir dans un seul appelPOST.
Créer un événement
Une fois qu’un modèle d’événement est configuré avec des jetons et des modèles, il est possible de créer des événements pour les contacts, les entreprises, les transactions et les tickets des clients. Les exemples ci-dessous concernent le modèle d’événementcontacts créé ci-dessus. Si le modèle d’événement ci-dessus n’est pas configuré pour disposer des jetons webinarName et webinarId, vous recevrez une erreur lors de la tentative de création d’événement. Voici un exemple POST pour la création d’un événement :
Remarque :
Les clés d’API de développeur et les jetons d’accès aux applications privées ne peuvent pas être utilisés comme authentification lors de la création d’événements. Pour créer un événement, le compte HubSpot associé doit accorder l’accès à votre application via OAuth. Une fois que vous recevez un jeton d’accès Oauth, vous pouvez l’utiliser pour ajouter des événements au compte.a.test.contact@email.com’(en supposant les modèles décrits dans Définition de modèles ci-dessus) :
Définir l’horodatage d’événement
L’horodatage d’événement détermine où l’événement apparaîtra dans la chronologie de l’objet. Par défaut, l’horodatage d’événement correspond à l’envoi de la commande POST. Vous pouvez personnaliser l’heure de l’événement en la fournissant dans le corps de la demande dans une propriété d’horodatage :Associer un événement à un objet de CRM
Pour créer un événement, vous devez associer l’événement à un contact, une entreprise ou une transaction dans le compte du client. Dans les exemples ci-dessus, objectType a été défini sur Contact et nous avons utilisé l’adresse e-mail pour associer l’événement à un contact. Les adresses e-mail doivent être uniques pour les contacts dans HubSpot. Si un contact avec l’adresse e-mail fournie existe déjà, ce contact sera mis à jour. S’il n’y a aucun contact existant, un nouveau contact sera créé. Par défaut, seule la propriété d’adresse e-mail sera fournie pour ce nouveau contact. Découvrez-en davantage sur l’horodatage de données d’événement dans les propriétés de contact pour ajouter des données supplémentaires aux propriétés de contact.vid du contact pour associer l’événement. Dans ces cas, vous utiliserez objectId dans le JSON de requête. Vous devez inclure le vid d’un contact existant, car vous ne pourrez pas créer de nouveaux contacts à l’aide de objectId. Cet exemple utilise objectId au lieu de l’adresse e-mail :
utk. Le jeton d’utilisateur est utilisé par le code de suivi HubSpot pour suivre les visiteurs et stocké dans le cookie hubspotutk. Utilisez le paramètre utk pour associer un événement à un contact via un jeton d’utilisateur. Remarque : Il n’est pas possible d’associer des événements à des visiteurs anonymes via un jeton d’utilisateur. Par conséquent, si l’événement est associé uniquement à utk et que le jeton fourni n’est pas déjà associé à un contact, aucun nouveau contact ne sera créé et l’événement ne sera pas visible dans HubSpot. Toutefois, l’événement apparaîtra dans la chronologie si un nouveau contact est associé au jeton d’utilisateur via un autre moyen (généralement via une soumission de formulaire comprenant hutk, ou via la méthode d’identification de l’API Code de suivi). C’est pourquoi nous recommandons d’inclure email en plus de utk pour vous assurer que l’événement est associé à un contact nouveau ou existant.
Si vous travaillez avec un modèle d’événement pour les contacts, il est possible d’inclure plusieurs paramètres d’identification avec l’événement, afin que toute combinaison des paramètres email, objectId et utk puisse être incluse. Si plusieurs paramètres sont inclus, objectId (vid) aura la priorité la plus élevée lors de la détermination du contact à associer à l’événement, suivi de utk, et email sera le paramètre le moins prioritaire. Cela signifie que vous pouvez mettre à jour l’adresse e-mail d’un objet existant en incluant une nouvelle adresse e-mail dans le paramètre email avec le vid d’un objet connu dans objectId. Cet exemple utilise l’adresse e-mail et le jeton d’utilisateur :
objectId pour associer l’événement à l’entreprise ou à la transaction. Pour les entreprises, objectId doit être défini sur le paramètre companyId de l’entreprise à laquelle vous souhaitez associer l’événement. Pour les transactions, vous définirez objectId sur le paramètre dealId de la transaction.
Dans l’exemple ci-dessous, en supposant que le modèle d’événement a été défini sur COMPANY pour objectType, cet événement sera associé à l’entreprise avec le paramètre companyId 528253914 :
Extensions de chronologie
Les extensions de chronologie peuvent être utilisées pour afficher des données provenant d’un système externe via un iFrame. Une fois inclus, l’événement affichera un lien vers une fenêtre modale qui affichera le contenu de l’iFrame. Les détails de l’iFrame sont définis dans le champ timelineIFrame, qui contient les champs suivants :linkLabel- Le texte utilisé pour afficher le lien qui affichera l’iFrame.headerLabel- Le libellé de la fenêtre modale qui affiche le contenu de l’iFrame.url- L’URI du contenu iFrame.width- La largeur de la fenêtre modale.height- La hauteur de la fenêtre modale.
url :
Horodater des données d’événement dans des propriétés d’objet de CRM
Dans de nombreux cas, vous souhaiterez modifier les propriétés des contacts, des entreprises ou des transactions auxquels vous ajoutez des événements. Cela se produit souvent dans les cas où l’ajout de l’événement crée un contact. Vous devrez probablement mettre à jour les propriétés de prénom et de nom pour le contact afin de ne pas créer de contact avec uniquement une adresse e-mail et un événement. Vous pouvez horodater les données sur l’objet associé à partir d’un événement par mappage de jetons d’événement personnalisés pour les propriétés de contact, d’entreprise et de transaction. Tenez compte de la commandePUT pour mettre à jour un modèle d’événement personnalisé ainsi que du champ objectPropertyName :
objectPropertyName est utilisé pour mapper ce jeton d’événement personnalisé à la propriété zz_webinar_name de l’objet contact. Cela signifie que lorsqu’un nouvel événement précisant un jeton webinarName est créé, la propriété zz_webinar_name du contact associé sera également définie. Vous pouvez définir cela pour des propriétés HubSpot prédéfinies ou personnalisées.
Par exemple, supposons que nous avons déjà créé un jeton companyName mentionnant une propriété personnalisée zz_company_name sur le contact. La création d’un événement comme celui-ci définira les propriétés zz_company_name et zz_webinar_name sur le contact avec l’adresse e-mail a.test.contact@email.com :
Comprendre extraData
Vous devrez peut-être ajouter des données détaillées à un événement qui ne correspondent pas à la structure jeton-valeur simple utilisée par les jetons de modèle d’événement. Vous devrez peut-être ajouter une liste ou une répartition hiérarchique à un événement d’intégration. C’est ici que extraData entre en jeu.
Vous pouvez ajouter un attribut extraData au corps JSON d’un événement. La valeur extraData peut être tout JSON valide. Par exemple :
extraData dans un modèle de détails :
extraData ne peut être mentionné que dans le modèle de détails pour un événement. Il ne peut pas être utilisé dans le modèle d’en-tête ou dans la segmentation de liste.
Configurer une icône personnalisée
Pour ajouter un attrait visuel à vos éléments de chronologie, vous souhaiterez ajouter une icône personnalisée. Ce fichier d’image pour cette icône doit :- Avoir une forme approximativement carrée
- Avoir un arrière-plan transparent
- Présenter son contenu au centre de l’icône
- Pouvoir être réduit jusqu’à 30 x 30 pixels
- Être égal ou inférieur à 5 Mo
Limites d’instances d’événements
Lors de la création d’un événement, chaque instance d’événement sérialisée est soumise aux limites de taille suivantes :- 500 octets pour l’ID d’instance d’événement
- 510 Ko par propriété/jeton
- 1 Mo de taille totale pour l’instance d’événement