Cartes CRM
Dans une application publique, vous pouvez créer des cartes CRM personnalisées pour afficher des informations provenant d'autres systèmes sur les fiche d'informations de contacts, d'entreprises, de transactions et de tickets HubSpot. Chaque application peut inclure jusqu'à 25 cartes CRM.
Exemple de cas d'utilisation : vous créez une intégration pour le marketplace des applications pour votre logiciel de suivi des bogues. Vous voulez faire apparaître les bogues suivis sur les fiches d'informations de contacts afin que les conseillers du support puissent les référencer lorsque vous travaillez avec les clients. Votre application peut définir une carte personnalisée qui affiche ces informations sur la fiche d'informations de contact HubSpot.
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. Par exemple, votre application peut inclure une action qui ouvre une fenêtre glissante pour afficher sa propre interface utilisateur dans HubSpot.
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. Par exemple, pour qu'une carte CRM apparaisse sur les fiches d'informations de contacts, l'application doit avoir les paramètres crm.objects.contacts.read
et crm.objects.contacts.write
. Si vous devez supprimer ultérieurement les paramètres d'objets CRM de votre application, vous devrez d'abord supprimer toutes les cartes existantes pour ces types d'objets.
Consultez la documentation OAuth pour plus de détails sur les domaines et la configuration de l'URL d'autorisation pour votre application.
Vous pouvez créer des cartes CRM pour votre application via l'API ou en modifiant votre application dans votre compte de développeur. Pour en savoir plus sur la configuration d'une carte via l'API, consultez l'onglet Points de terminaison en haut de l'article.
Pour créer une carte CRM à l'aide de l'interface utilisateur de HubSpot :
- Dans votre compte de développeur de HubSpot, accédez à Apps dans la navigation principale.
- Sélectionnez l'application à laquelle vous souhaitez ajouter une carte.
- Dans le menu latéral de gauche, sélectionnez Cartes CRM.
- Cliquez sur Créer une carte CRM dans l'angle supérieur droit.
Découvrez ci-dessous les options de configuration dans chaque onglet.
Lorsqu'un utilisateur HubSpot affiche une fiche d'informations CRM dans laquelle la carte CRM est activée, HubSpot formulera une demande de récupération de données à l'intégration. Cette demande est faite à l'URL cible spécifiée, qui comprend un ensemble de paramètres de requête par défaut, ainsi que des paramètres supplémentaires contenant des données de propriété telles que spécifiées dans les paramètres de la carte.
-
Dans le champ URL de récupération des données, saisissez l'URL à partir de laquelle vous allez récupérer les données. Dans l'API, cette URL est ajoutée au champ
targetUrl
. - Dans la section Types de fiches d'informations cibles, cliquez pour activer les options afin de sélectionner les fiches d'informations CRM dans lesquelles la carte apparaîtra. Ensuite, utilisez les menus déroulants Propriétés envoyées par HubSpot pour sélectionner les propriétés HubSpot qui seront incluses en tant que paramètres de requête dans l'URL de la requête. Dans l'API, chaque type de fiche d'informations et ses propriétés correspondantes sont ajoutés en tant qu'objets dans le tableau
objectTypes
.
La configuration ci-dessus entraînerait l'envoi par HubSpot de sa requête GET
comme suit.
Parameter | Type | Description |
---|---|---|
userId
| Default | L'ID de l'utilisateur HubSpot qui a chargé la fiche d'informations CRM. |
userEmail
| Default | L'adresse e-mail de l'utilisateur qui a chargé la fiche d'informations CRM. |
associatedObjectId
| Default | L'ID de la fiche d'informations CRM qui a été chargée. |
associatedObjectType
| Default | Le type de fiche d'informations CRM qui a été chargée (par exemple, contact, entreprise, transaction). |
portalId
| Default | L'ID du compte HubSpot dans lequel la fiche d'informations CRM a été chargée. |
firstname
| Custom | Le prénom du contact, tel que spécifié dans le menu déroulant Propriétés envoyées par HubSpot (dans l'application) et le tableau |
type de client
| Custom | L'adresse e-mail du contact, tel que spécifié dans le menu déroulant Propriétés envoyées par HubSpot (dans l'application) et le tableau |
lastname
| Custom | Le nom du contact, tel que spécifié dans le menu déroulant Propriétés envoyées par HubSpot (dans l'application) et le tableau |
Remarque : les requêtes expireront au bout de cinq secondes. Dans ce délai, la connexion doit être effectuée en trois secondes.
Vous trouverez ci-dessous un exemple de réponse que l'intégrateur pourrait fournir à la requête ci-dessus.
results array
An array of up to five valid card properties. If more card properties are available for a specific CRM object, your app can link to them. |
objectId number (required)
A unique ID for this object. |
title string (required)
The title of this object. |
link string
The URL that the user can follow to get more details about the object. This property is optional, but if no objects have a link, you should provide a value of |
created string (required)
A custom property as defined in the card's settings that denotes the date of the object's creation. |
priority string (required)
A custom property as defined in the card's settings that denotes external ticket's priority level. |
actions array
A list of available actions a user can take. |
properties string
A list of custom properties that aren't defined in the card settings. You can use this list to display a specific object's unique properties. These properties will be shown in the order they're provided, but after the properties defined in the card settings. |
settingsAction object
An iframe action that enables users to update the app's settings. |
primaryAction object
The primary action for a record type, typically a creation action. |
secondaryActions array
A list of actions displayed on the card. |
Pour s'assurer que les requêtes proviennent bien de HubSpot, l'en-tête de requête suivant est inclus. Cet en-tête contiendra un hachage du secret de l'application pour votre application ainsi que les détails de la requête.
X-HubSpot-Signature: <some base64 string>
Pour vérifier cette signature, effectuez les étapes suivantes :
- Créez une chaîne qui regroupe les éléments suivants :
<app secret>
+<HTTP method>
+<URL>
+<request body> (if present)
. - Créez un hachage SHA-256 de la chaîne résultante.
- Comparez la valeur de hachage à la signature. Si elle est égale, la requête a été validée. Si elle ne correspond pas, cette requête peut avoir été modifiée en transit ou quelqu'un peut usurper les demandes à votre point de terminaison.
Dans l'onglet Propriétés de la carte, définissez toutes les propriétés personnalisées que vous souhaitez que HubSpot affiche sur la carte CRM. Une fois définie, l'intégration peut remplir ces propriétés en les incluant dans sa réponse.
-
- Cliquez sur Ajouter une propriété pour ajouter une nouvelle propriété à afficher sur la carte. La charge utile que vous fournissez en réponse à l'appel d'extraction de données doit contenir des valeurs pour toutes ces propriétés.
- Dans le panneau de droite, définissez le nom unique, le libellé d'affichage et le type de données de la propriété. Vous pouvez choisir parmi les types suivants : Devise, Date, Datetime, E-mail, Lien, Numérique, Statut et Chaîne. Découvrez-en davantage sur l'utilisation des types de propriétés d'extension.
- Cliquez sur Ajouter pour enregistrer la propriété.
Lorsque HubSpot envoie sa requête de données, l'intégration peut fournir des valeurs pour ces propriétés dans sa réponse ainsi que d'autres valeurs dans chaque objet dans la propriété results
. Outre les propriétés configurées dans cet onglet, l'intégration peut également inclure ses propres propriétés personnalisées sans avoir besoin de les définir dans les paramètres de la carte.
Par exemple, dans la réponse ci-dessous, les paramètres created
et priority
sont tous deux définis dans l'onglet Propriétés de la carte, tandis que le tableau properties
envoie ses propres définitions et valeurs de propriétés. Ces propriétés spécifiques à l'objet doivent être définies par objet.
Lors de l'envoi de propriétés personnalisées, le champ dataType
de chaque propriété peut être défini sur l'un des éléments suivants : CURRENCY
, DATE
, DATETIME
, EMAIL
, LINK
, NUMERIC
, STATUS
, STRING
. Selon le type de propriété, l'intégration peut devoir fournir des champs supplémentaires. Découvrez-en davantage ci-dessous sur chaque type de propriété.
Les propriétés CURRENCY
doivent inclure un paramètre currencyCode
, qui doit être un code ISO 4217 valide. Cela garantira que l'utilisateur voit le symbole de devise et la mise en forme des chiffres corrects.
Les propriétés DATE
doivent être au format aaaa-mm-jj
. Ces propriétés seront affichées dans un format correspondant aux paramètres régionaux de l'utilisateur. Si vous devez inclure un horodatage, vous devez plutôt utiliser une propriété DATETIME
.
DATETIME
properties indicate a specific time and must be provided as milliseconds since epoch. These properties will be displayed in a format appropriate to the user's locale.
EMAIL
properties are for values that contain an email address. These properties will be displayed as mailto links.
LINK
properties display hyperlinks and open in a new window. You can specify a linkLabel
, otherwise the URL itself will be displayed.
STATUS
properties display as colored indicators. To define a status property, the integration must provide an optionType
that describes the possible statuses. Statuses include:
DEFAULT
: GreySUCCESS
: GreenWARNING
: YellowDANGER
: RedINFO
: Blue
Les demandes incluront un en-tête
X-HubSpot-Signature
. Consultez les signatures de requête pour plus d'informations.Les URL d'action sont accessibles dans le champ uri
d'une action. À l'instar de la demande de récupération de données, les hooks d'action incluront un ensemble par défaut de paramètres de requête. Vous pouvez inclure d'autres paramètres de requête en incluant un champ AssociatedObjectProperties
dans l'action.
La réponse variera en fonction du type d'action. Découvrez-en davantage ci-dessous sur les types d'actions.
IFRAME
actions will open a modal containing an iframe pointing at the provided URL.
When the user is done completing an action inside the iframe, the modal should close and return the user to the CRM record they started from. To close the modal, the integration can use window.postMessage
to signal to the CRM that the user is done. The following messages are accepted:
{"action": "DONE"}
: the user has successfully competed the action.{"action": "CANCEL"}
: the user has canceled the action.
ACTION_HOOK
actions send a server-side request to the integrator. The only UI a users sees for this action is a success or error message. This type of action is useful for simple operations that require no further input from the user.
The httpMethod
can be set to GET
, POST
, PUT
, DELETE
, or PATCH
. If using GET
or DELETE
, the associatedObjectProperties
values will be appended to the request URL as query parameters. Otherwise, the properties will be sent in the request body.
Les actions CONFIRMATION_ACTION_HOOK
ont un comportement identique à celui des actions ACTION_HOOK
, à 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.
La propriété httpMethod
peut être définie sur GET
, POST
, PUT
, DELETE
ou PATCH
. Si vous utilisez la propriété GET
ou DELETE
, les valeurs AssociatedObjectProperties
seront ajoutées à l'URL de la requête en tant que paramètres de requête. Dans le cas contraire, les propriétés seront envoyées dans le corps de la requête.
Merci d'avoir partagé votre avis.