Cartes CRM

Les cartes CRM personnalisées permettent aux informations d'autres systèmes d'apparaître sur les fiches d'informations de contact, d'entreprise, de transaction ou de ticket. Grâce à cette fonctionnalité, les applications peuvent créer des cartes personnalisées pour afficher ces données. Si vous souhaitez que vos données se trouvent directement dans HubSpot mais qu'aucun des objets natifs ne répond à vos besoins, découvrez les objets personnalisés.

Exemple de cas d'utilisation : Votre équipe d'ingénieurs utilise un service logiciel pour suivre les bugs, mais vos représentants du service client utilisent HubSpot. Vos représentants souhaitent consulter des informations concernant leurs clients sans quitter HubSpot. Votre application peut définir une carte personnalisée qui affiche ces informations sur la fiche d'informations de contact HubSpot.

Fonctionnement

Les cartes peuvent être définies dans les paramètres de fonctionnalité de votre application. Une fois que l'application est installée et qu'un utilisateur consulte les fiches d'informations du CRM cibles, HubSpot effectue une demande sortante à l'application, récupère les données pertinentes et les affiche dans une carte sur la page de la fiche d'informations. Les applications peuvent également spécifier des actions personnalisées que l'utilisateur peut effectuer en fonction de ces informations. Un exemple d'action personnalisée serait l'ouverture d'une fenêtre modale et l'affichage de l'interface utilisateur de l'application dans HubSpot.

Voici un exemple de carte CRM :

CRM_Card_1

Voici un exemple de flux de données pour l'affichage des propriétés de la carte dans le CRM :

CRM_card_diagram

 

Configuration des cartes CRM

Les cartes CRM peuvent être créées et configurées dans votre compte de développeur. Les détails individuels sur la carte sont représentés par des propriétés de carte. Les titres de ces propriétés peuvent rediriger vers le système externe de l'intégrateur (facultatif). Notez que la ligne « Powered by » sur la carte utilisera le nom de l'application à partir des paramètres de l'application.

Dans le tableau de bord des applications, choisissez l'application où vous souhaitez ajouter une carte, puis accédez à Cartes CRM. Cliquez sur le bouton Créer une carte CRM pour commencer.

Screen Shot 2020-01-14 at 7.36.35 PM

Exigences des domaines

Pour créer des cartes CRM personnalisées, votre application doit demander les domaines OAuth requis pour modifier les fiches d'informations de CRM dans lesquelles votre carte apparaîtra. Autrement dit, vous demandez le domaine contacts pour configurer une carte pour des contacts, des entreprises ou des transactions, et le domaine tickets pour des tickets.

Consultez la documentation OAuth pour plus de détails sur les domaines et la configuration de l'URL d'autorisation pour votre application.

Supprimer des domaines

Si votre application utilise déjà des cartes CRM, vous ne pourrez pas supprimer les domaines contacts ou tickets tant que vous ne supprimerez pas toutes les cartes existantes pour les types d'objets associés.

 

Créer de nouvelles cartes

La création de modèles de carte est la première étape d'utilisation des cartes CRM. Voici ce qu'un utilisateur verra :

CRM_card_2

 

Configuration de cartes via l'API

Découvrez-en davantage sur la gestion des cartes via l'API dans l'onglet Points de terminaison.

Configuration de cartes depuis l'interface utilisateur des paramètres de l'application

Vous pouvez également créer et gérer des cartes CRM* dans votre compte de développeur, dans les paramètres de fonctionnalité de l'application (voir les instructions précédentes).

Example_CRM_card_3

* Vous pouvez créer jusqu'à 25 cartes CRM par application.


Documents associés

Comprendre le CRM

Événements de chronologie

Demandes de récupération de données

Comme mentionné dans l'onglet Vue d'ensemble, HubSpot effectue une demande de récupération de données à votre application lorsqu'un utilisateur consulte la fiche d'informations de CRM associée. Ces demandes sont envoyées à l'élément fetch/targetUrl spécifié de la carte avec une charge utile fournissant des informations pour la fiche d'informations de CRM associée.

Les réponses peuvent contenir jusqu'à 5 propriétés de carte. Si plusieurs propriétés de carte sont disponibles pour un objet de CRM spécifique, votre application peut rediriger vers celles-ci.

Notez que la demande expirera après 5 secondes. Dans ce délai, la connexion doit être effectuée en 3 secondes. 

Exemple de demande de récupération de données :

GET : https://example.com/demo-tickets?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com

 
Avec un en-tête :
X-HubSpot-Signature: <some base64 string>

L'en-tête X-HubSpot-Signature  permet de vérifier qu'une demande provient bien de HubSpot. Consultez les signatures de demande pour plus d'informations.

Paramètres de demande :
  • userId : l'ID d'utilisateur numérique du client qui demande les données.
  • userEmail : l'adresse HubSpot de l'utilisateur qui demande les données.
  • portalId : l'ID de compte HubSpot du client qui demande les données. Le compte et le portail sont utilisés de manière interchangeable. 
  • associatedObjectId : l'ID de l'objet actuel, en fonction de associatedObjectType. Il s'agira de companyId, dealId, contact vID ou objectId pour les tickets.
  • associatedObjectType : le type d'objet pour lequel l'utilisateur demande des données (contact, company, deal ou ticket). Il s'agira de l'un des éléments associatedHubSpotObjectTypes fourni pour ce type de fiche d'informations.
  • Et les valeurs pour l'un des éléments associatedHubSpotObjectTypeProperties demandés. Si l'une des propriétés de demande n'est pas définie pour l'objet actuel, elle ne sera pas répertoriée dans la chaîne de demande. Dans l'exemple ci-dessus, le domaine de propriété d'entreprise est inclus. Les propriétés de demande peuvent être définies dans l'interface utilisateur des paramètres de l'application, comme vous pouvez le voir dans la capture d'écran ci-dessous : 

Associated_Objects

Exemple de réponse :
// example response { "results": [ { "objectId": 245, "title": "API-22: APIs working too fast", "link": "http://example.com/1", "created": "2016-09-15", "priority": "HIGH", "project": "API", "reported_by": "msmith@hubspot.com", "description": "Customer reported that the APIs are just running too fast. This is causing a problem in that they're so happy.", "reporter_type": "Account Manager", "status": "In Progress", "ticket_type": "Bug", "updated": "2016-09-28", "actions": [ { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/edit-iframe-contents", "label": "Edit", "associatedObjectProperties": [] }, { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/reassign-iframe-contents", "label": "Reassign", "associatedObjectProperties": [] }, { "type": "ACTION_HOOK", "httpMethod": "PUT", "associatedObjectProperties": [], "uri": "https://example.com/tickets/245/resolve", "label": "Resolve" }, { "type": "CONFIRMATION_ACTION_HOOK", "confirmationMessage": "Are you sure you want to delete this ticket?", "confirmButtonText": "Yes", "cancelButtonText": "No", "httpMethod": "DELETE", "associatedObjectProperties": [ "protected_account" ], "uri": "https://example.com/tickets/245", "label": "Delete" } ] }, { "objectId": 988, "title": "API-54: Question about bulk APIs", "link": "http://example.com/2", "created": "2016-08-04", "priority": "HIGH", "project": "API", "reported_by": "ksmith@hubspot.com", "description": "Customer is not able to find documentation about our bulk Contacts APIs.", "reporter_type": "Support Rep", "status": "Resolved", "ticket_type": "Bug", "updated": "2016-09-23", "properties": [ { "label": "Resolved by", "dataType": "EMAIL", "value": "ijones@hubspot.com" }, { "label": "Resolution type", "dataType": "STRING", "value": "Referred to documentation" }, { "label": "Resolution impact", "dataType": "CURRENCY", "value": "94.34", "currencyCode": "GBP" } ], "actions": [ { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/edit-iframe-contents", "label": "Edit" }, { "type": "CONFIRMATION_ACTION_HOOK", "confirmationMessage": "Are you sure you want to delete this ticket?", "confirmButtonText": "Yes", "cancelButtonText": "No", "httpMethod": "DELETE", "associatedObjectProperties": [ "protected_account" ], "uri": "https://example.com/tickets/245", "label": "Delete" } ] } ], "settingsAction": { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/settings-iframe-contents", "label": "Settings" }, "primaryAction": { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/create-iframe-contents", "label": "Create Ticket" } }
Définitions :
  • results : une liste comprenant jusqu'à 5 propriétés de carte valides. 
  • results[].objectId : un ID unique pour cet objet. Cette propriété est obligatoire.
  • results[].title : le titre de cet objet. Cette propriété est obligatoire.
  • results[].link : l'URI que l'utilisateur peut suivre pour obtenir plus de détails sur cet objet. Cette propriété est facultative, mais si tous les objets n'ont pas de lien, vous devez fournir une valeur nulle.
  • results[].properties : une liste des propriétés personnalisées qui ne sont pas définies dans les paramètres de la carte. Vous pouvez utiliser cette liste pour afficher les propriétés uniques d'un objet spécifique. Ces propriétés seront affichées dans l'ordre dans lequel elles sont fournies, mais après les propriétés définies dans les paramètres de la carte. Cette propriété est facultative.
  • results[].actions : une liste des actions disponibles qu'un utilisateur peut effectuer pour cet objet. Consultez les types d'action pour obtenir des détails sur les actions. Cette propriété est facultative.
  • totalCount : le nombre total de propriétés de carte disponibles, s'il y a plus de 5 propriétés associées à l'objet de CRM demandé. Cette propriété est facultative.
  • allItemsLink : un URI affichant toutes les propriétés de carte associées à l'objet de CRM demandé, s'il y en a plus de 5. Cette propriété est facultative.
  • itemLabel : le libellé à utiliser dans le lien Afficher plus, par exemple Afficher plus de tickets. Cette propriété est facultative et si elle n'est pas fournie, elle sera définie par défaut sur le titre de la carte.
  • settingsAction : une action d'iFrame donnant aux utilisateurs la possibilité de mettre à jour les paramètres de l'application. Consultez les types d'action pour obtenir des détails sur les actions. Cette propriété est facultative.
  • primaryAction : l'action principale pour un type de fiche d'informations, généralement une action de création. Consultez les types d'action pour obtenir des détails sur les actions. Cette propriété est facultative.
  • secondaryActions : une liste d'actions affichées au niveau de la carte. Consultez les types d'action pour obtenir des détails sur les actions. Cette propriété est facultative.

Outre les propriétés ci-dessus, l'intégrateur peut fournir des valeurs pour les propriétés définies dans les paramètres de la carte. Dans l'exemple ci-dessus, la propriété JSON créée

"created":"2016-08-04"

fournit une valeur pour cet objet pour la propriété created prédéfinie.

CRM_card_5

Gérer les hooks d'action 

Lorsqu'un utilisateur clique sur une action définie comme un hook d'action, HubSpot envoie une demande à l'aide de la méthode URI et HTTP indiquée dans la définition d'action.

Exemple de demande :

DELETE https://example.com/tickets/245?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com

Avec un en-tête :
X-HubSpot-Signature: <some base64 string>
Paramètres de demande :
  • userId : l'ID d'utilisateur numérique du client qui demande les données.
  • userEmail : l'adresse utilisateur HubSpot du client qui demande les données.
  • associatedObjectId : l'ID de l'objet actuel, en fonction de associatedObjectType. Il s'agira de companyId, dealId, contact vID ou objectId pour les tickets.
  • associatedObjectType : le type d'objet pour lequel l'utilisateur demande des données (contact, company, deal ou ticket).
  • portalId : l'ID de compte (également appelé HubID) du client qui demande les données.
  • Et les valeurs pour l'un des éléments associatedObjectProperties demandés. Si l'une des propriétés de demande n'est pas définie pour l'objet actuel, elle ne sera pas répertoriée dans la chaîne de demande. Dans l'exemple ci-dessus, le domaine de propriété d'entreprise est inclus.

L'en-tête X-HubSpot-Signature permet à l'intégrateur de vérifier qu'une demande provient bien de HubSpot. Consultez les signatures de demande pour plus d'informations.

Exemple de réponse :
{"message": "Successfully deleted object"}

HubSpot essaiera d'analyser les réponses aux hooks d'action en tant que JSON et recherchera une propriété de message. L'utilisateur recevra un message de réussite ou d'échec.

Le code de statut de réponse 2XX affichera un message de réussite et 4XX ou 5XX affichera un message d'erreur.

 

Types d'action

Les sections suivantes fournissent des informations sur chaque type d'action qui peut être spécifié.

Actions d'iFrame

Lorsqu'un utilisateur clique sur une action d'iFrame, une boîte de dialogue modale avec un iFrame pointant sur l'URL fournie sera ouverte.

Exemple d'iFrame :
// { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/iframe- contents", "label": "Edit", "associatedObjectProperties": [ "some_crm_property" ] }
Définitions :
  • type : doit être IFRAME pour indiquer qu'il s'agit d'une action d'iFrame.
  • width, height : les dimensions souhaitées de l'iFrame.
  • uri : l'URI ouvert dans l'iFrame.
  • label : le libellé affiché dans le menu déroulant des actions.
  • associatedObjectProperties : Une liste des propriétés sur le contact, l'entreprise, la transaction ou le ticket associé(e). Les valeurs de propriété pour l'objet actuel seront ajoutées à l'URI en tant que paramètres de demande lors de l'ouverture de l'iFrame.

Signaler la fermeture de la fenêtre modale

Lorsque l'utilisateur finalise une action d'iFrame, la fenêtre modale doit se fermer et rediriger l'utilisateur vers l'écran de CRM initial. Pour fermer la boîte de dialogue modale, l'application peut utiliser window.postMessage. Les messages suivants sont acceptés :

  • {"action": "DONE"} - L'utilisateur a correctement finalisé l'action.
  • {"action": "CANCEL"} - L'utilisateur a annulé l'action.
Exemple : window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Remarque : les fenêtres modales d'iFrame consultées via une action d'iFrame auront une largeur adaptable. 

 

Actions de hook d'action

Les actions de hook d'action envoient une demande côté serveur à une application. La seule interface utilisateur qu'un utilisateur voit pour cette action est un message de réussite ou d'erreur. Ce type d'action est utile pour des opérations simples qui ne nécessitent pas d'entrée utilisateur supplémentaire.

Exemple d'action de hook d'action :
// { "type": "ACTION_HOOK", "httpMethod": "POST", "uri": "https://example.com/action-hook", "label": "Example action", "associatedObjectProperties": [ "some_crm_property" ] }
Définitions :
  • type : doit être ACTION_HOOK pour indiquer qu'il s'agit d'une action de hook d'action.
  • httpMethod : la méthode HTTP à utiliser lors de la demande. Cela peut être GET, POST, PUT, DELETE ou PATCH.
  • uri : l'URI de la demande à effectuer.
  • label : le libellé à afficher dans le menu déroulant des actions.
  • associatedObjectProperties : Une liste des propriétés sur le contact, l'entreprise, la transaction ou le ticket associé(e). Si httpMethod est GET ou DELETE, ces valeurs de propriété seront ajoutées à l'URI de la demande comme paramètres de demande. Autrement, elles seront envoyées en tant que corps de demande JSON.

Consultez Gérer les hooks d'action pour plus de détails sur la mise en œuvre du point de terminaison d'action.

Actions de confirmation

Les actions de confirmation ont un comportement identique à celui des hooks d'action, à l'exception d'une boîte de dialogue de confirmation affichée pour l'utilisateur avant l'exécution de la demande côté serveur.

 

// { "type": "CONFIRMATION_ACTION_HOOK", "httpMethod": "POST", "uri": "https://example.com/action-hook", "label": "Example action", "associatedObjectProperties": [ "some_crm_property" ], "confirmationMessage": "Are you sure you want to run example action?", "confirmButtonText": "Yes", "cancelButtonText": "No" }
Définitions :
  • type : doit être ACTION_HOOK pour indiquer qu'il s'agit d'une action de hook d'action.
  • httpMethod : la méthode HTTP à utiliser lors de la demande. Cela peut être GET, POST, PUT, DELETE ou PATCH.
  • uri : l'URI de la demande à effectuer.
  • label : le libellé à afficher dans le menu déroulant des actions.
  • associatedObjectProperties : Une liste des propriétés sur le contact, l'entreprise, la transaction ou le ticket associé(e). Si httpMethod est GET ou DELETE, ces valeurs de propriété seront ajoutées à l'URI de la demande comme paramètres de demande. Autrement, elles seront envoyées en tant que corps de demande JSON.

Consultez Gérer les hooks d'action pour plus de détails sur la mise en œuvre du point de terminaison d'action.

Actions de confirmation

Les actions de confirmation ont un comportement identique à celui des hooks d'action, à l'exception d'une boîte de dialogue de confirmation affichée pour l'utilisateur avant l'exécution de la demande côté serveur.

Définitions :
  • type : doit être CONFIRMATION_ACTION_HOOK pour indiquer qu'il s'agit d'une action de hook d'action de confirmation.
  • httpMethod : la méthode HTTP à utiliser lors de la demande. Cela peut être GET, POST, PUT, DELETE ou PATCH.
  • uri : l'URI de la demande à effectuer.
  • label : le libellé à afficher dans le menu déroulant des actions.
  • associatedObjectProperties : Une liste des propriétés sur le contact, l'entreprise, la transaction ou le ticket associé(e). Si httpMethod est GET ou DELETE, ces valeurs de propriété seront ajoutées à l'URI de la demande comme paramètres de demande. Autrement, elles seront envoyées en tant que corps de demande JSON.
  • confirmationMessage : le message à afficher à l'utilisateur dans la boîte de dialogue de confirmation.
  • confirmButtonText : le texte du bouton OK. Il est facultatif, car le texte de bouton sera par défaut défini sur « OK ».
  • cancelButtonText : le texte du bouton Annuler. Il est facultatif, car le texte de bouton sera par défaut défini sur « Annuler ».

Consultez Gérer les hooks d'action pour plus de détails sur la mise en œuvre du point de terminaison d'action.


Cet article vous a-t-il été utile ? *
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.