CRM-Karten

ÜberblickEndpunkteWebhooks

Benutzerdefinierte CRM-Karten ermöglichen es, Informationen aus anderen Systemen in HubSpot-Kontakt-, Unternehmens-, Deal- oder Ticket-Datensätzen anzuzeigen. Mithilfe dieser Funktion können Apps benutzerdefinierte Karten erstellen, um diese Daten anzuzeigen. Wenn sich Ihre Daten direkt in HubSpot befinden sollen, jedoch keines der nativen Objekte Ihren Anforderungen entspricht, sollten Sie überlegen, ob vielleicht benutzerdefinierte Objekte Ihre Anforderungen erfüllen.

Beispiel für einen Anwendungsfall: Ihr Entwicklerteam verwendet einen Softwaredienst, um Bugs nachzuverfolgen, aber Ihre Kundendienstmitarbeiter nutzen HubSpot. Ihre Vertriebsmitarbeiter möchten Informationen zu den Bugs ihrer Kunden sehen, ohne HubSpot verlassen zu müssen. Ihre App kann eine benutzerdefinierte Karte definieren, auf der diese Informationen direkt im HubSpot-Kontaktdatensatz angezeigt werden.

So funktioniert es

Karten 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. Ein Beispiel für eine benutzerdefinierte Aktion ist das Öffnen eines modalen Dialogfeldes und die Anzeige der eigenen UI der App in HubSpot.

Hier ist ein Beispiel für eine CRM-Karte:

CRM_Card_1

Und hier ist ein Beispiel für den Datenfluss, um Karteneigenschaften im CRM anzuzeigen:

CRM_card_diagram

 

Einrichten von CRM-Karten

CRM-Karten können in Ihrem Entwickler-Account erstellt und konfiguriert werden. Einzelne Details auf der Karte werden durch Karteneigenschaften dargestellt, und die Titel für diese Eigenschaften können (optional) zum System des Integrators verlinken. Bitte beachten Sie, dass der Text „Powered by“ auf der Karte den App-Namen von Ihren App-Einstellungen verwendet.

Wählen Sie im Apps-Dashboard die App aus, für die Sie eine Karte hinzufügen möchten, und gehen Sie dann zu „CRM-Karten“. Klicken Sie auf die Schaltfläche „CRM-Karte erstellen“, um loszulegen.

Screenshot 2020-01-14 um 7.36.35 PM

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. Dies bedeutet, dass Sie den contacts-Bereich anfordern, um eine Karte für Kontakte, Unternehmen oder Deals einzurichten, sowie den tickets-Bereich für Tickets.

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

Entfernen von Bereichen

Wenn Ihre App bereits CRM-Karten verwendet, können Sie die contacts- oder tickets-Bereiche erst entfernen, wenn Sie alle vorhandenen Karten für die zugehörigen Objekttypen gelöscht haben.

 

Erstellen neuer Karten

Das Erstellen von Kartenvorlagen ist der erste Schritt bei der Verwendung von CRM-Karten. Dies ist, was ein Benutzer sieht:

CRM_card_2

 

Konfigurieren von Karten über die API

Erfahren Sie mehr über das Verwalten von Karten über die API auf der Registerkarte „Endpunkte”.

Konfigurieren von Karten über die Benutzeroberfläche mit den App-Einstellungen

Sie können CRM-Karten* auch in Ihrem Entwickler-Account unter den Funktionseinstellungen Ihrer App erstellen und verwalten. (Siehe vorherige Anweisungen.)

Example_CRM_card_3

*Sie können bis zu 25 CRM-Karten pro App erstellen.

Verwandte Dokumente

Grundlegendes zum CRM

Chronik-Events

Datenabrufanfragen

Wie auf der Registerkarte „Übersicht“ erläutert, stellt HubSpot jedes Mal eine Datenabrufanfrage an Ihre App, wenn ein Benutzer den zugehörigen CRM-Datensatz aufruft. Diese Anfragen werden an die festgelegte Abruf-/Ziel-URL der Karte gesendet. Eine Payload stellt dabei Details für den zugehörigen CRM-Datensatz bereit.

Antworten können bis zu fünf Karteneigenschaften enthalten. Wenn für ein bestimmtes CRM-Objekt weitere Karteneigenschaften verfügbar sind, kann Ihre App zu ihnen verlinken.

Beachten Sie, dass die Zeit für die Anfrage nach fünf Sekunden abläuft. Innerhalb dieser Zeit muss eine Verbindung mit 3 Sekunden hergestellt werden. 

Beispiel für eine Datenabrufanfrage

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

 
Mit einem Header:
X-HubSpot-Signatur: <some base64 string>

Der X-HubSpot-Signatur-Header stellt eine Verifizierung dafür bereit, dass die Anfrage von HubSpot stammt. Weitere Informationen finden Sie unter Anfragesignaturen.

Abfrageparameter:
  • userId: Die numerische Benutzer-ID des Kunden, der Daten anfordert.
  • userEmail: Die HubSpot-Adresse des Benutzers, der Daten anfordert.
  • portalId: Die HubSpot-Account-ID des Kunden, der Daten anfordert. Account und Portal werden synonym verwendet. 
  • associatedObjectId: Die ID für das aktuelle Objekt, abhängig vom associatedObjectType. Dies ist dann die companyId, dealId, contact vID oder  objectId für Tickets.
  • associatedObjectType: Der Objekttyp, zu dem der Benutzer Daten anfordert (contact, company, deal oder ticket). Dies ist einer der für diesen Datensatztyp bereitgestellten associatedHubSpotObjectTypes.
  • Und Werte für die angeforderten associatedHubSpotObjectTypeProperties. Wenn eine der Anfrageeigenschaften nicht für das aktuelle Objekt definiert ist, wird sie nicht in der Abfragezeichenfolge aufgeführt. Im obigen Beispiel ist die Domain der Unternehmenseigenschaft enthalten. Anfrageeigenschaften können, wie im nachfolgenden Screenshot zu sehen, über die Benutzeroberfläche mit den App-Einstellungen definiert werden: 

Associated_Objects

Beispielantwort:
// 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" } }
Definitionen:
  • results: Eine Liste mit bis zu fünf gültigen Karteneigenschaften. 
  • results[].objectId: Eine eindeutige ID für dieses Objekt. Diese Eigenschaft ist erforderlich.
  • results[].title: Der Titel dieses Objekts. Diese Eigenschaft ist erforderlich.
  • results[].link: Der URI, dem der Benutzer folgen kann, um weitere Details zu diesem Objekt abzurufen. Diese Eigenschaft ist optional, wenn jedoch keines der Objekte über einen Link verfügt, sollten Sie den Wert Null angeben.
  • results[].properties: Eine Liste benutzerdefinierter Eigenschaften, die nicht in den Karteneinstellungen definiert sind. Sie können diese Liste verwenden, um eindeutige Eigenschaften eines bestimmten Objekts anzuzeigen. Diese Eigenschaften werden in der Reihenfolge angezeigt, in der sie angegeben werden, aber nach den in den Karteneinstellungen definierten Eigenschaften. Diese Eigenschaft ist optional.
  • results[].actions: Eine Liste mit verfügbaren Aktionen, die ein Benutzer für dieses Objekt durchführen kann. Weitere Informationen zum Angeben von Aktionen finden Sie unter Aktionstypen. Diese Eigenschaft ist optional.
  • totalCount: Die Gesamtanzahl der verfügbaren Karteneigenschaften, wenn es mehr als fünf gibt, die mit dem angeforderten CRM-Objekt zusammenhängen. Diese Eigenschaft ist optional.
  • allItemsLink: Ein URI, der alle Karteneigenschaften im Zusammenhang mit dem angeforderten CRM-Objekte anzeigt, wenn es mehr als fünf gibt. Diese Eigenschaft ist optional.
  • itemLabel: Das Label, das im Link „Mehr anzeigen“ verwendet werden soll, z. B. „Mehr Tickets anzeigen". Diese Eigenschaft ist optional. Wird sie nicht angegeben, wird standardmäßig der Kartentitel angezeigt.
  • settingsAction: Eine Iframe-Aktion, mit der Benutzer die Einstellungen der App aktualisieren können. Weitere Informationen zum Angeben von Aktionen finden Sie unter Aktionstypen. Diese Eigenschaft ist optional.
  • primaryAction: Die primäre Aktion für einen Datensatztyp, in der Regel eine erstellende Aktion. Weitere Informationen zum Angeben von Aktionen finden Sie unter Aktionstypen. Diese Eigenschaft ist optional.
  • secondaryActions: Eine Liste der auf Kartenebene angezeigten Aktionen. Weitere Informationen zum Angeben von Aktionen finden Sie unter Aktionstypen. Diese Eigenschaft ist optional.

Zusätzlich zu den oben genannten Eigenschaften kann der Integrator Werte für die in den Karteneinstellungen definierten Eigenschaften bereitstellen. Im obigen Beispiel ist dies die erstellte JSON-Eigenschaft:

"created":"2016-08-04"

Stellt einen Wert für dieses Objekt für die vordefinierte created-Eigenschaft bereit.

CRM_card_5

Verarbeiten von Action-Hooks 

Wenn ein Benutzer auf eine Aktion klickt, die als Action-Hook definiert ist, sendet HubSpot eine Anfrage mithilfe der in der Aktionsrichtlinie festgelegten URI und HTTP-Methode.

Beispielanfrage:

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

Mit einem Header:
X-HubSpot-Signatur: <some base64 string>
Abfrageparameter:
  • userId: Die numerische Benutzer-ID des Kunden, der Daten anfordert.
  • userEmail: Die HubSpot-Benutzeradresse des Kunden, der Daten anfordert.
  • associatedObjectId: Die ID für das aktuelle Objekt, abhängig vom associatedObjectType. Dies ist dann die companyId, dealId, contact vid oder  objectId für Tickets.
  • associatedObjectType: Der Objekttyp, zu dem der Benutzer Daten anfordert (contact, company, deal oder ticket).
  • portalId: Die Account-ID (auch Hub-ID genannt) des Kunden, der Daten anfordert.
  • Und Werte für die angeforderten associatedObjectProperties. Wenn eine der angeforderten Eigenschaften nicht für das aktuelle Objekt definiert ist, wird sie nicht in der Abfragezeichenfolge aufgeführt. Im obigen Beispiel ist die Domain der Unternehmenseigenschaft enthalten.

Anhand des X-HubSpot-Signatur-Headers kann der Integrator verifizieren, dass eine Anfrage von HubSpot kam. Weitere Informationen finden Sie unter Anfragesignaturen.

Beispielantwort:
{"message": "Objekt erfolgreich gelöscht"}

HubSpot versucht, Antworten auf Action-Hooks als JSON zu analysieren, und sucht nach einer Nachrichteneigenschaft. Der Benutzer erhält sowohl bei einem Erfolg als auch bei einem Fehlschlagen eine entsprechende Meldung.

Ein Antwortstatuscode von 2XX bedeutet eine Erfolgsmeldung und ein Antwortstatuscode von 4XX oder 5XX bedeutet eine Fehlermeldung.

 

Aktionstypen

Die folgenden Abschnitte enthalten Details zu jeder Art von Aktion, die angegeben werden kann.

Iframe-Aktionen

Wenn ein Benutzer auf eine iframe-Aktion klickt, wird ein modales Dialogfeld mit einem iframe geöffnet, der auf die angegebene URL verweist.

Beispiel-iframe-Aktion:
// { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/iframe- contents", "label": "Edit", "associatedObjectProperties": [ "some_crm_property" ] }
Definitionen:
  • type: Sollte IFRAME sein, um anzugeben, dass dies eine iframe-Aktion ist.
  • width, height: Die gewünschten iframe-Abmessungen.
  • uri: Der im iframe geöffnete URI.
  • label: Das im Aktions-Dropdown-Menü angezeigte Label.
  • associatedObjectProperties: Eine Liste der Eigenschaften im verknüpften Kontakt, Unternehmen, Deal oder Ticket. Die Eigenschaftswerte für das aktuelle Objekt werden als Abfrageparameter an die URI angehängt, wenn Sie den iframe öffnen.

Anweisen des modalen Dialogfeldes zum Schließen

Wenn der Benutzer eine iframe-Aktion abgeschlossen hat, sollte das modale Dialogdialogfeld geschlossen werden und der Benutzer zum ursprünglichen CRM-Bildschirm zurückgeleitet werden. Um das modale Dialogfeld zu schließen, kann die App eine window.postMessage verwenden. Die folgenden Nachrichten werden akzeptiert:

  • {"Aktion": "FERTIG"} – Der Benutzer hat die Aktion erfolgreich abgeschlossen.
  • {"Aktion": "ABBRECHEN"} – Der Benutzer hat die Aktion abgebrochen.
Beispiel: window.parent.postMessage(JSON.stringify({"Aktion": "FERTIG"}), "*");

Hinweis: Modale iframe-Dialogfelder, die über eine iframe-Aktion aufgerufen werden, haben eine responsive Breite. 

 

Action-Hook-Aktionen

Action-Hook-Aktionen senden einen serverseitige Anfrage an eine App. Der einzige UI, die ein Benutzer für diese Aktion sieht, ist eine Erfolgsmeldung oder eine Fehlermeldung. Diese Art von Aktion ist hilfreich bei einfachen Operationen, die keine weitere Benutzereingabe erfordern.

Beispiel für eine Action-Hook-Aktion:
// { "type": "ACTION_HOOK", "httpMethod": "POST", "uri": "https://example.com/action-hook", "label": "Example action", "associatedObjectProperties": [ "some_crm_property" ] }
Definitionen:
  • type: Sollte ACTION_HOOK sein, um anzugeben, dass dies eine Action-Hook-Aktion ist.
  • httpMethod: Die HTTP-Methode, die für die Anfrage verwendet werden soll. Dies kann GET, POST, PUT, DELETE oder PATCH sein.
  • uri: Der URI der zu stellenden Anfrage.
  • label: Das Label, das im Aktions-Dropdown-Menü angezeigt wird.
  • associatedObjectProperties: Eine Liste der Eigenschaften im verknüpften Kontakt, Unternehmen, Deal oder Ticket. Wenn httpMethod den Wert GET oder DELETE hat, werden diese Eigenschaftswerte an den URI der Anfrage als Abfrageparameter angehängt. Andernfalls werden sie als ein JSON-Anfragetext gesendet.

Weitere Informationen zur Implementierung des Aktionspunkts finden Sie unter  Verarbeiten von Action-Hooks.

Bestätigungsaktionen

Bestätigungsaktionen verhalten sich wie Action-Hooks, außer dass dem Benutzer ein Bestätigungsdialogfeld angezeigt wird, bevor die serverseitige Anfrage ausgeführt wird.

 

// { "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" }
Definitionen:
  • type: Sollte ACTION_HOOK sein, um anzugeben, dass dies eine Action-Hook-Aktion ist.
  • httpMethod: Die HTTP-Methode, die für die Anfrage verwendet werden soll. Dies kann GET, POST, PUT, DELETE oder PATCH sein.
  • uri: Der URI der zu stellenden Anfrage.
  • label: Das Label, das im Aktions-Dropdown-Menü angezeigt wird.
  • associatedObjectProperties: Eine Liste der Eigenschaften im verknüpften Kontakt, Unternehmen, Deal oder Ticket. Wenn httpMethod den Wert GET oder DELETE hat, werden diese Eigenschaftswerte an den URI der Anfrage als Abfrageparameter angehängt. Andernfalls werden sie als ein JSON-Anfragetext gesendet.

Weitere Informationen zur Implementierung des Aktionspunkts finden Sie unter  Verarbeiten von Action-Hooks.

Bestätigungsaktionen

Bestätigungsaktionen verhalten sich wie Action-Hooks, außer dass dem Benutzer ein Bestätigungsdialogfeld angezeigt wird, bevor die serverseitige Anfrage ausgeführt wird.

Definitionen:
  • type: Sollte CONFIRMATION_ACTION_HOOK sein, um anzugeben, dass dies eine Bestätigungs-Action-Hook-Aktion ist.
  • httpMethod: Die HTTP-Methode, die für die Anfrage verwendet werden soll. Dies kann GET, POST, PUT, DELETE oder PATCH sein.
  • uri: Der URI der zu stellenden Anfrage.
  • label: Das Label, das im Aktions-Dropdown-Menü angezeigt wird.
  • associatedObjectProperties: Eine Liste der Eigenschaften im verknüpften Kontakt, Unternehmen, Deal oder Ticket. Wenn httpMethod den Wert GET oder DELETE hat, werden diese Eigenschaftswerte an den URI der Anfrage als Abfrageparameter angehängt. Andernfalls werden sie als ein JSON-Anfragetext gesendet.
  • confirmationMessage: Die Nachricht, die dem Benutzer im Bestätigungsdialogfeld angezeigt wird.
  • confirmButtonText: Der Text für die Schaltfläche „OK“. Dies ist optional, da der Schaltflächentext standardmäßig „OK“ ist.
  • cancelButtonText: Text für die Schaltfläche „Abbrechen“. Dies ist optional, da der Schaltflächentext standardmäßig „Abbrechen“ ist.

Weitere Informationen zur Implementierung des Aktionspunkts finden Sie unter  Verarbeiten von Action-Hooks.

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.