Événements de chronologie

Les extensions de CRM permettent aux autres systèmes d'apparaître sur des objets de contact, d'entreprise ou de transaction HubSpot. Les points de terminaison des événements de chronologie permettent de créer des événements chronologiques personnalisés. Si vous préférez que vos données soient modifiables par les utilisateurs, mais qu'aucun des objets CRM par défaut ne correspond à vos besoins, découvrez les objets personnalisés.

Par exemple, vous souhaitez mieux segmenter vos contacts en fonction de leurs interactions avec votre entreprise et votre contenu. Pour cela, vous devez en savoir davantage sur eux. Votre application peut créer des événements personnalisés (contacts inscrits mais n'ayant pas assisté à un webinar récent, variante d'un flux de souscription complété par un contact, etc.) qui offrent davantage de contexte sur les interactions des contacts avec votre entreprise.

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 champ objectType. 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.

Assurez-vous de remplacer <<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 (voir Définition de modèles ci-dessous).

Cette demande 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.

Vous commencerez avec un brouillon de votre nouveau modèle d'événement. Une fois que vous avez défini le type d'objet ainsi que les modèles de détails et d'en-tête pour l'événement, cliquez sur Créer.

Lorsque vous créez ou modifiez votre modèle d'événement, définissez tous les jetons que vous souhaitez utiliser dans l'onglet Données.

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, pour les contacts, utilisées pour la segmentation de liste et l'automatisation. 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.

De même, une commande GET renverra tous les jetons définis sur un modèle d'événement :

Les types de jeton pris en charge comprennent :

• string
• number
• enumeration — Un ensemble d'options. Consultez l'exemple de webinarType ci-dessus.
• date — Toutes les dates doivent être en millisecondes selon Unix.

Remarque : Les jetons d'événement ne peuvent pas être appelés log ou lookup. Ces jetons sont réservés en tant qu'aides par Handlebars.js, la bibliothèque utilisée pour afficher les événements dans l'application. Pour plus d'informations, consultez les documents relatifs à Handlebars.js ici.

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 jeton webinarCode dans le modèle en utilisant .

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 avec PUT :

Notez l'utilisation de la directive #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 :

Un clic sur Afficher les détails affiche le modèle de détails :

Pour définir l'icône affichée à côté des événements, consultez Configurer une icône personnalisée ci-dessous.

Le texte « Example App Name » ci-dessus est le nom de l'application. Dans la chronologie du CRM, les événements peuvent être filtrés par application.

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 appel POST. 

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énement contacts 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 :

Cela génère un événement sur la chronologie de 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 :

Cela est recommandé si vous connaissez l'heure exacte d'une action. Dans cet exemple, si l'horodatage pour l'inscription au webinar est connu, il est recommandé de le fournir dans cette commande POST.

Les horodatages peuvent être en millisecondes ou au format ISO 8601.

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.

Si vous travaillez avec des contacts connus, vous pouvez également utiliser le 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 :

Vous pouvez également associer un événement avec un contact via un jeton d'utilisateur, ou 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 :

Outre les contacts, il est également possible de créer des modèles d'événement pour des entreprises et des transactions. Pour ces modèles d'événement, vous devez utiliser 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.

Par exemple, l'utilisation de ces données pour un événement :

Créerait cet événement, y compris le lien « Afficher les données externes » :

Un clic sur ce lien ouvrira une fenêtre modale qui affichera la page définie dans 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 commande PUT pour mettre à jour un modèle d'événement personnalisé ainsi que du champ objectPropertyName :

Le paramètre 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 :

Remarque : Si un jeton d'événement est horodaté pour une propriété personnalisée et que la propriété personnalisée n'est pas présente pour un compte HubSpot, la valeur sera toujours définie pour l'événement, mais elle sera ignorée pour l'objet correspondant.

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 de extraData peut être tout JSON valide. Par exemple :

Voici un exemple d'utilisation de extraData dans un modèle de détails :

Cela générera un événement de chronologie qui ressemblera à ceci :

Remarque : L'attribut 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.

Pour définir l'icône utilisée pour les événements de chronologie, accédez à Événements de chronologie. Cliquez sur l'image de l'espace réservé ou sur l'icône existante pour la définir ou la mettre à jour.

Une fois que vous avez défini une icône, celle-ci sera affichée à côté des événements de chronologie associés à cette application :

Documents associés

Comprendre le CRM

Cartes CRM