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 :
Voici un exemple de flux de données pour l'affichage des propriétés de la carte dans le CRM :
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.
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 :
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).
* Vous pouvez créer jusqu'à 25 cartes CRM par application.
Documents associés
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 deassociatedObjectType
. Il s'agira decompanyId
,dealId
,contact vID
ouobjectId
pour les tickets.associatedObjectType
: le type d'objet pour lequel l'utilisateur demande des données (contact
,company
,deal
outicket
). Il s'agira de l'un des élémentsassociatedHubSpotObjectTypes
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 :
Exemple de réponse :
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.
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 deassociatedObjectType
. Il s'agira decompanyId
,dealId
,contact vID
ouobjectId
pour les tickets.associatedObjectType
: le type d'objet pour lequel l'utilisateur demande des données (contact
,company
,deal
outicket
).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 :
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 :
Définitions :
type
: doit êtreACTION_HOOK
pour indiquer qu'il s'agit d'une action de hook d'action.httpMethod
: la méthodeHTTP
à utiliser lors de la demande. Cela peut êtreGET
,POST
,PUT
,DELETE
ouPATCH
.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). SihttpMethod
estGET
ouDELETE
, 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 êtreACTION_HOOK
pour indiquer qu'il s'agit d'une action de hook d'action.httpMethod
: la méthodeHTTP
à utiliser lors de la demande. Cela peut êtreGET
,POST
,PUT
,DELETE
ouPATCH
.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). SihttpMethod
estGET
ouDELETE
, 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 êtreCONFIRMATION_ACTION_HOOK
pour indiquer qu'il s'agit d'une action de hook d'action de confirmation.httpMethod
: la méthodeHTTP
à utiliser lors de la demande. Cela peut êtreGET
,POST
,PUT
,DELETE
ouPATCH
.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). SihttpMethod
estGET
ouDELETE
, 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.
Merci d'avoir partagé votre avis.