Événements marketing

Un événement marketing est un objet de CRM similaire aux contacts et aux entreprises. Celui-ci vous permet de suivre et d'associer des événements marketing, tels qu'un webinaire, à d'autres objets de CRM HubSpot. Découvrez ci-dessous comment utiliser l'API d'événements marketing pour intégrer des événements marketing dans une application.

• Exigences des domaines
• Points de terminaison de participation à l'événement
• Configurer les paramètres d'application
  • Étape 1 : Créez une API dans votre application
  • Étape 2 : Fournissez à HubSpot le chemin d'URL vers votre API

Pour effectuer une demande API vers l'un des points de terminaison d'événement marketing, les champs d'application suivants sont requis :

• crm.objects.marketing_events.read : autorise la récupération des données relatives aux événements marketing et à la participation.
• crm.objects.marketing_events.write : accorde la permission de créer, de supprimer ou d'apporter des modifications aux informations relatives à un événement marketing.

Lors de l'authentification des appels effectués par votre application, vous pouvez utiliser un jeton d'accès d'application privée ou OAuth. Découvrez-en davantage sur les méthodes d'authentification. Pour la liste complète des points de terminaison disponibles, cliquez sur l'onglet Points de terminaison en haut de cet article.

Vous pouvez créer ou mettre à jour des événements marketing en effectuant une demande POST vers /marketing/v3/marketing-events/events/upsert. Vous pouvez inclure tous les éléments customProperties qui correspondent aux événements que vous souhaitez mettre à jour dans le champ inputs de votre corps de demande, ainsi que tout autre détail de votre événement (y compris son nom, son heure de début et sa description).

Si un événement marketing existe déjà avec l'ID spécifié dans votre demande, il sera mis à jour. Sinon, un nouvel événement sera créé.

Par exemple, la demande suivante créera un événement avec un ID de 4 nommé « Cours de cuisine virtuel » :

Vous pouvez consulter la liste complète de tous les champs disponibles que vous pouvez inclure dans votre demande en cliquant sur l'onglet Points de terminaison en haut de cet article.

Les points de terminaison de participation aux événements vous permettent d'enregistrer un statut d'abonnement entre un contact HubSpot et un événement marketing. Par exemple, vous pouvez utiliser ce point de terminaison pour enregistrer l'inscription d'un contact HubSpot à un événement marketing.

Il existe deux points de terminaison que vous pouvez utiliser pour mettre à jour le statut de participation d'un contact. Si vous utilisiez précédemment les points de terminaison/upsert ou /email-upsert pour mettre à jour le statut d'un participant, vous pouvez plutôt utiliser les points de terminaison répertoriés ci-dessous pour maintenir la même fonctionnalité tout en renseignant la durée de présence du contact sur sa chronologie :

• Si vous souhaitez utiliser les identifiants des contacts existants :
  • Faites une demande POST à /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/create, en utilisant l'ID de l'événement de votre application externe pour externalEventId.
  • Dans le corps de la demande, fournissez un objet inputs qui comprend les champs suivants :
    • interactionDateTime : date et heure auxquelles le contact s'est inscrit à l'événement.
    • vid : l'ID d'un contact existant.
• Si vous souhaitez utiliser l'adresse e-mail d'un des participants à l'événement :
  • Faites une demande POST à /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/email-create.
  • Dans le corps de la demande, fournissez un objet inputs qui comprend les champs suivants :
    • interactionDateTime : date et heure auxquelles le contact s'est inscrit à l'événement.
    • e-mail : adresse e-mail du participant en tant que valeur du champ d'adresse e-mail dans une entrée. 
  • Si l'adresse e-mail que vous incluez ne correspond pas à l'adresse d'un contact existant, un nouveau contact sera créé.

Pour les deux points de terminaison ci-dessus, fournissez les valeurs suivantes pour les paramètres de chemin correspondants :

• externalEventId : l'ID de l'événement marketing.
•  subscriberState : une énumération qui correspond au nouveau statut de participation du contact :
  • REGISTERED : indique que le contact HubSpot s'est inscrit à l'événement.
  • ATTENDED : indique que le contact HubSpot a assisté à l'événement. Si vous mettez à jour le statut d'un contact vers ATTENDED, vous pouvez également inclure les horodatages joinedAt et leftAt comme paramètres dans le corps de la demande, spécifié dans le format ISO8601 Instant.
  • CANCELLED : indique que le contact HubSpot qui s'était préalablement inscrit à l'événement a annulé son inscription.

Une fois votre événement terminé, vous pouvez le marquer comme terminé et calculer les indicateurs de présence (par exemple, la durée de présence pour tous les participants) en faisant une demande POST vers /marketing/v3/marketing-events/events/{externalEventId}/complete. Notez que cette action est irréversible, vous ne devez donc invoquer ce point de terminaison qu'une fois que tous les événements de changement d'état de présence ont déjà eu lieu. 

Une certaine configuration est requise pour permettre aux événements marketing de se synchroniser correctement avec HubSpot.

Si vous envoyez à HubSpot un changement de statut d'abonné (par exemple, une inscription ou une annulation), HubSpot vérifiera d'abord si un événement marketing existe pour l'ID d'événement spécifié. Si ce n'est pas le cas, HubSpot appellera le point de terminaison configuré pour votre application afin de récupérer les détails de l'événement marketing, puis créera l'événement dans HubSpot et publiera le changement de statut d'abonné.

Ceci est fourni pour des raisons de commodité ; cependant, il est toujours recommandé que vous créiez vous-même les événements marketing via nos méthodes CRUD, fournies dans l'onglet Points de terminaison en haut de cet article, sans vous appuyer sur cette fonctionnalité pour créer vos événements marketing dans HubSpot.

Pour ce faire, HubSpot exige que chaque application qui utilise des événements marketing définisse une API pour récupérer des informations sur un événement marketing spécifique.

Exigences :

• Accepte :
  • externalAccountId : paramètre de requête spécifiant accountId pour le client dans l'application externe.
  • appId : paramètre de requête qui spécifie l'ID de l'application HubSpot qui demande les détails de l'événement. Il s'agira de l'ID de votre application.
  • externalEventId : paramètre de chemin dans l'URL de la demande qui spécifie l'ID de l'événement dans l'application externe sur laquelle HubSpot nécessite des détails.
• Renvoie :
  • Un objet JSON qui fournit les détails de l'événement marketing, qui comprend les champs suivants détaillés dans le tableau ci-dessous :

HubSpot envoie également un en-tête X-HubSpot-Signature-v3 que vous pouvez utiliser pour vérifier que la demande provient de HubSpot. Découvrez-en davantage sur les signatures de demande pour plus de détails sur la signature et comment la valider.

Maintenant que vous avez créé l'API dans votre application qui renverra un objet fournissant les détails d'un événement marketing spécifique, vous devez fournir à HubSpot le chemin d'URL de votre API en effectuant une demande POST vers /marketing/v3/marketing-events/{appId}/settings. Cela permettra à HubSpot de déterminer comment faire des demandes à votre application pour obtenir les détails d'un événement marketing.

Dans le corps de votre demande POST, spécifiez votre URL à l'aide du champ eventDetailsURL. eventDetailsURL doit répondre aux deux exigences suivantes :

• Il doit contenir au moins une séquence de caractères %s, que nous utilisons pour remplacer dans l'ID de l'événement (externalEventId) comme paramètre de chemin d'accès.
• Il doit s'agir du chemin complet vers la ressource API, y compris le préfixe https :// et le nom de domaine (par exemple, my.event.app).

Par exemple, si vous configurez un eventDetailsURL de https://my.event.app/events/%s et que vous devez faire une demande pour récupérer les détails d'un événement avec l'ID 1234-event-XYZ, pour l'application HubSpot avec l'ID app-101 et le compte avec l'ID ABC-account-789, HubSpot fera une demande GET à :

https://my.event.app/events/1234-event-XYZ?appId=app-101&externalAccountId=ABC-account-789