CRM-Karten

ÜberblickEndpunkte

Innerhalb einer öffentlichen App können Sie benutzerdefinierte CRM-Karten erstellen, um Informationen aus anderen Systemen in HubSpot-Kontakt-, Unternehmens-, Deal- und Ticket-Datensätzen anzuzeigen. Jede App kann bis zu 25 CRM-Karten enthalten.

Bitte beachten: Die in diesem Artikel referenzierten CRM-Karten unterscheiden sich von den benutzerdefinierten Karten, die Sie als UI-Erweiterungen mit Projekten erstellen können. Die in diesem Artikel enthaltenen CRM-Karten sind für die Verwendung mit öffentlichen Apps bestimmt, nicht für private Apps, die mit Projekten erstellt wurden.

Anwendungsfall als Beispiel: Sie erstellen eine Integration für den App Marketplace für Ihre Bug-Tracking-Software. Sie möchten in der Lage sein, nachverfolgte Bugs in Kontaktdatensätzen zu erkennen, damit Supportmitarbeiter bei der Zusammenarbeit mit Kunden auf sie verweisen können. Ihre App kann eine benutzerdefinierte Karte definieren, auf der diese Informationen direkt im HubSpot-Kontaktdatensatz angezeigt werden.
CRM_Card_1Karten können als Teil der Funktionseinstellungen Ihrer App definiert werden. Sobald die App installiert ist und ein Benutzer die Ziel-CRM-Datensätze anzeigt, stellt HubSpot eine ausgehende Anfrage an die App, ruft die relevanten Daten ab und zeigt sie auf einer Karte auf der Datensatzseite an. Apps können ebenfalls benutzerdefinierte Aktionen angeben, die der Benutzer basierend auf diesen Informationen durchführen kann. Beispielsweise könnte Ihre App eine Aktion zum Öffnen eines Modalfensters zum Anzeigen der eigenen Benutzeroberfläche der App in HubSpot enthalten.

CRM_card_diagram

Anforderungen an den Bereich

Um benutzerdefinierte CRM-Karten zu erstellen, muss Ihre App die OAuth-Bereiche anfordern, die erforderlich sind, um die CRM-Datensätze zu ändern, in denen Ihre Karte angezeigt wird. Damit beispielsweise eine CRM-Karte in Kontaktdatensätzen angezeigt wird, muss die App über die Bereiche crm.objects.contacts.read und crm.objects.contacts.write verfügen. Wenn Sie später CRM-Objektbereiche von Ihrer App entfernen müssen, müssen Sie zunächst alle vorhandenen Karten für diese Objekttypen löschen.

Weitere Informationen zu Bereichen und zum Einrichten der Autorisierungs-URL für Ihre App finden Sie in der OAuth-Dokumentation.

Eine CRM-Karte erstellen

Sie können CRM-Karten für Ihre App entweder über die API oder durch Bearbeiten Ihrer App in Ihrem Entwickler-Account erstellen. Weitere Informationen zum Konfigurieren einer Karte über die API finden Sie auf der Registerkarte Endpunkte oben im Artikel.

So erstellen Sie eine CRM-Karte mithilfe der Benutzeroberfläche von HubSpot:

    • Gehen Sie in Ihrem HubSpot-Entwickler-Account in der Hauptnavigation zu Apps.
    • Wählen Sie die App aus, in der Sie eine Karte hinzufügen möchten.
    • Wählen Sie im Menü der linken Seitenleiste CRM-Karten aus.
    • Klicken Sie oben rechts auf CRM-CRM-Karte erstellen.
      private-app-create-crm-card

Im Folgenden erfahren Sie mehr über die Konfigurationsoptionen auf den einzelnen Registerkarten.

Datenanfrage

Wenn ein Benutzer in HubSpot einen CRM-Datensatz anzeigt, auf dem sich die CRM-Karte befindet, führt HubSpot eine Datenabrufanfrage an die Integration durch. Diese Anfrage wird an die angegebene Ziel-URL durchgeführt, die eine Reihe von Standardabfrageparametern sowie zusätzliche Parameter enthält, die Eigenschaftsdaten enthalten, wie in den Karteneinstellungen angegeben.

private-app-create-crm-card-data-request-tab

  • Geben Sie im Feld Datenabruf-URL die URL ein, von der Sie Daten abrufen möchten. In der API wird diese URL dem targetUrl-Feld hinzugefügt. 

  • Klicken Sie im Abschnitt Zieldatensatztypen auf, um die Schalter, um sie zu aktivieren und auszuwählen, in welchen CRM-Datensätzen die Karte angezeigt wird. Verwenden Sie dann die Vom HubSpot gesendete Eigenschaften-Dropdown-Menüs, um die HubSpot-Eigenschaften auszuwählen, die als Abfrageparameter in die Anfrage-URL aufgenommen werden. In der API werden jeder Datensatztyp und seine entsprechenden Eigenschaften als Objekte im objectTypes-Array hinzugefügt.
// Example data fetch configuration { "title": "New CRM Card", "fetch": { "targetUrl": "https://www.example.com/demo-fetch", "objectTypes": [ { "name": "contacts", "propertiesToSend": [ "firstname", "email", "lastname" ] } ] } ... }

Beispielanfrage

Die obige Konfiguration würde dazu führen, dass HubSpot seine GET-Anfrage wie folgt sendet.

https://www.example.com/demo-fetch?userId=12345&userEmail=loggedinuser@hubspot.com&associatedObjectId=53701&associatedObjectType=CONTACT&portalId=987654&firstname=Tim&email=timrobinson@itysl.com&lastname=Robinson
Use this table to describe parameters / fields
ParameterTypeDescription
userId
Default

Die ID des HubSpot-Benutzers, der den CRM-Datensatz geladen hat.

userEmail
Default

Die E-Mail-Adresse des Benutzers, der den CRM-Datensatz geladen hat.

associatedObjectId
Default

Die ID des CRM-Datensatzes, der geladen wurde.

associatedObjectType
Default

Der Typ des CRM-Datensatzes, der geladen wurde (z. B. Kontakt, Unternehmen, Deal).

portalId
Default

Die ID des HubSpot-Accounts, in das der CRM-Datensatz geladen wurde.

firstname
Custom

Der Vorname des Kontakts, wie im Dropdown-Menü Vom HubSpot gesendete Eigenschaften (in der App) und im propertiesToSend-Array (API) angegeben.

email
Custom

Die E-Mail-Adresse des Kontakts, wie im Dropdown-Menü Vom HubSpot gesendete Eigenschaften (in der App) und im propertiesToSend-Array (API) angegeben.

lastname
Custom

Der Nachname des Kontakts, wie im Dropdown-Menü Vom HubSpot gesendete Eigenschaften (in der App) und im propertiesToSend-Array (API) angegeben.

Bitte beachten: Anfragen laufen nach fünf Sekunden ab. In diesem Account muss innerhalb von drei Sekunden eine Verknüpfung erstellt werden. 

Beispielantwort

Nachfolgend finden Sie eine Beispielantwort, die der Integrator auf die obige Anfrage bereitstellen könnte.

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 null.
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.
// 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", "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" } }

Anfragesignaturen

Um sicherzustellen, dass die Anfragen tatsächlich von HubSpot kommen, ist der folgende Anfrage-Header enthalten. Dieser Header enthält einen Hash des App-Geheimnisses für Ihre Anwendung und die Details der Anfrage.

X-HubSpot-Signature: <some base64 string>

Um diese Signatur zu überprüfen, führen Sie die folgenden Schritte aus:

  1. Erstellen Sie eine Zeichenfolge, die Folgendes miteinander verkettet: <app secret> + <HTTP method> + <URL> + <request body> (falls vorhanden).
  2. Erstellen Sie einen SHA-256-Hash von der resultierenden Zeichenfolge.
  3. Vergleichen Sie den Hash-Wert mit der Signatur. Wenn sie gleich sind, hat die Anfrage die Validierung bestanden. Wenn die Werte nicht übereinstimmen, wurde die Anfrage möglicherweise während des Transfers manipuliert, oder jemand spooft Anfragen an Ihren Endpunkt.

Erfahren Sie mehr über das Validieren von Anfragen von HubSpot.

Karteneigenschaften

Definieren Sie auf der Registerkarte Karteneigenschaften alle benutzerdefinierten Eigenschaften, die HubSpot auf der CRM-Karte anzeigen soll. Einmal definiert, kann die Integration diese Eigenschaften füllen, indem sie sie in ihre Antwort einbezieht.

    • Klicken Sie auf Eigenschaft hinzufügen, um eine neue Eigenschaft für die anzuzeigende Karte hinzuzufügen. Die Payload, die Sie als Antwort auf den Aufruf zum Abrufen von Daten bereitstellen, sollte Werte für alle diese Eigenschaften enthalten.
    • Legen Sie im rechten Bereich den eindeutigen Namen, das Anzeigelabel und den Datentyp der Eigenschaft fest. Sie können aus den folgenden Typen auswählen: Währung, Datum, Datum/Uhrzeit, E-Mail, Link, Numerisch, Status und Zeichenfolge. Erfahren Sie mehr über die Verwendung von Erweiterungseigenschaftstypen.
    • Klicken Sie auf Hinzufügen, um die Eigenschaft zu speichern.
      private-app-create-crm-card-card-properties-tab

Wenn HubSpot seine Datenanfrage sendet, kann die Integration Werte für diese Eigenschaften in ihrer Antwort neben anderen Werten in den einzelnen Objekten in results bereitstellen. Zusätzlich zu den auf dieser Registerkarte konfigurierten Eigenschaften kann die Integration auch eigene benutzerdefinierte Eigenschaften enthalten, ohne dass diese in den Einstellungen der Karte definiert werden müssen.

Beispielsweise werden in der Antwort unten sowohl created als auch priority auf der Registerkarte Karteneigenschaften definiert, während das properties-Array seine eigenen Eigenschaftsdefinitionen und -werte sendet. Diese objektspezifischen Eigenschaften müssen pro Objekt definiert werden.

// Example object within a response { "objectId": 988, "title": "API-54: Question about bulk APIs", "link": "http://example.com/2", "created": "2016-08-04", "priority": "HIGH", "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": [ ... ] }

Beim Senden benutzerdefinierter Eigenschaften kann das dataType-Feld für jede Eigenschaft auf einen der folgenden Werte festgelegt werden: CURRENCY, DATE, DATETIME, EMAIL, LINK, NUMERIC, STATUS, STRING. Abhängig vom Eigenschaftstyp muss die Integration möglicherweise zusätzliche Felder bereitstellen. Im Folgenden erfahren Sie mehr über die einzelnen Eigenschaftstypen.

Währungseigenschaften

CURRENCY-Eigenschaften müssen einen currencyCode enthalten, der ein gültiger ISO 4217-Code sein muss. Dadurch wird sichergestellt, dass der Benutzer das richtige Währungssymbol und die richtige Zahlenformatierung sieht.

// Example custom currency property { "results": [ { "properties": [ { "label": "Resolution impact", "dataType": "CURRENCY", "value": "94.34", "currencyCode": "GBP" } ] } ] }

Datumseigenschaften

DATE-Eigenschaften sollten das Format jjjj-mm-tt haben. Diese Eigenschaften werden in einem Format angezeigt, das dem Gebietsschema des Benutzers entspricht. Wenn Sie einen Zeitstempel einfügen müssen, sollten Sie stattdessen eine DATETIME-Eigenschaft verwenden.

// Example custom date property { "results": [ { "properties": [ { "label": "Date", "dataType": "DATE", "value": "2023-10-13" } ] } ] }

Datetime properties

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.

// Example custom datetime property { "results": [ { "properties": [ { "label": "Timestamp", "dataType": "DATETIME", "value": "1697233678777" } ] } ] }

Email properties

EMAIL properties are for values that contain an email address. These properties will be displayed as mailto links.

// Example custom email property { "results": [ { "properties": [ { "label": "Email address", "dataType": "EMAIL", "value": "hobbes.baron@gmail.com" } ] } ] }

Link properties

LINK properties display hyperlinks and open in a new window. You can specify a linkLabel, otherwise the URL itself will be displayed. 

// Example custom link property { "results": [ { "properties": [ { "label": "Link property", "dataType": "LINK", "value": "https://www.hubspot.com", "linkLabel": "Test link" } ] } ] }

Numeric properties

NUMERIC properties display numbers. 

// Example custom datetime property { "results": [ { "properties": [ { "label": "Number", "dataType": "NUMERIC", "value": "123.45" } ] } ] }

Status properties

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: Grey
  • SUCCESS: Green
  • WARNING: Yellow
  • DANGER: Red
  • INFO: Blue
// Example custom datetime property { "results": [ { "properties": [ { "label": "Status", "dataType": "STATUS", "value": "Errors occurring", "optionType": "DANGER" } ] } ] }

String properties

STRING properties display text.

// Example custom datetime property { "results": [ { "properties": [ { "label": "First name", "dataType": "STRING", "value": "Tim Robinson" } ] } ] }

Custom actions

Auf der Registerkarte Benutzerdefinierte Aktionen können Sie die Basis-URLs definieren, die angefordert werden, wenn ein Benutzer auf eine Aktionsschaltfläche klickt. Sie können mehrere Aktions-URLs für verschiedene Aktionen in Ihre CRM-Karte aufnehmen. Kartenaktionen müssen einen auf dieser Registerkarte angegebenen Endpunkt aufrufen.
private-app-create-crm-card-custom-actions-tabAktionshooks und Bestätigungshook-Anfragen enthalten einen X-HubSpot-Signature-Header zur Überprüfung der Anfrage. Iframe-Aktionsanfragen enthalten keine Anfragesignatur. Siehe Anfragesignaturen für weitere Informationen.

Auf Aktions-URLs wird im uri-Feld in einer Aktion zugegriffen. Ähnlich wie bei einer Datenabrufanfrage enthalten Action-Hooks einen Standardsatz von Abfrageparametern. Sie können andere Abfrageparameter einbeziehen, indem Sie ein zugeordnetes associatedObjectProperties-Feld in die Aktion einbeziehen.

Die Antwort hängt vom Aktionstyp ab. Im Folgenden erfahren Sie mehr über Aktionstypen.

Action types

Iframe actions

IFRAME actions will open a modal containing an iframe pointing at the provided URL. No request signature is sent when the iframe is opened from the CRM UI. This is because the iframe URL is returned in the original data fetch request, and no additional proxy requests are needed.

// Example iframe action { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/iframe-contents", "label": "Edit", "associatedObjectProperties": [ "some_crm_property" ] }

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.
// Example iframe close message window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Action hook actions

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. An X-HubSpot-Signature header will be included in the request for verification. Learn more about request signatures.

// Example action hook action { "type": "ACTION_HOOK", "httpMethod": "POST", "uri": "https://example.com/action-hook", "label": "Example action", "associatedObjectProperties": [ "some_crm_property" ] }

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.

// Example iframe close message window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Confirmation actions

CONFIRMATION_ACTION_HOOK-Aktionen verhalten sich wie ACTION_HOOK-Aktionen, außer dass dem Benutzer ein Bestätigungsdialogfeld angezeigt wird, bevor die serverseitige Anfrage ausgeführt wird. Ein X-HubSpot-Signature-Header wird in die Anfrage zur Überprüfung aufgenommen. Erfahren Sie mehr über Anfragesignaturen.

// Example action hook action { "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" }

Die httpMethod kann auf GET, POST, PUT, DELETE oder PATCH festgelegt werden.  Bei Verwendung von GET oder DELETE werden die zugeordneten associatedObjectProperties-Werte als Abfrageparameter an die Anfrage-URL angehängt. Andernfalls werden die Eigenschaften im Anfragetext gesendet.

War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.