CRMカード

公開アプリ内でカスタムCRMカードを作成し、HubSpotのコンタクト、会社、取引、チケットのレコードに他のシステムからの情報を表示できます。各アプリには、最大25枚のCRMカードを含めることができます。

注:この記事で参照しているCRMカードは、プロジェクトでUI拡張機能として作成できるカスタムカードとは異なります。この記事に記載するCRMカードは、プロジェクトで作成された非公開アプリではなく、公開アプリで使用するように意図されているものです。

使用例:アプリマーケットプレイスに掲載する、バグ追跡用ソフトウェアの連携を構築しています。サポート担当者がユーザーに対応する際に参照できるよう、コンタクトレコードに追跡対象のバグが表示されるようにしたいと考えています。この情報は、貴社のアプリにカスタムカードを定義することで、HubSpotコンタクトレコード上に表示できます。
CRM_Card_1カードはアプリの機能設定の一部として定義できます。アプリをインストールしたユーザーがターゲットのCRMレコードを表示すると、HubSpotはアプリにリクエストを送信して関連するデータを取得し、レコードページ上のカードにそのデータを表示します。アプリには、この情報に基づいてユーザーが実行できるカスタムアクションを指定することもできます。例えば、HubSpot内でアプリ独自のUIを表示するためのモーダルを開くアクションをアプリに組み込むことができます。

CRM_card_diagram

スコープの要件

カスタムCRMカードを作成するアプリは、カードを表示するCRMレコードの変更に必要なOAuthスコープをリクエストする必要があります。例えば、CRMカードをコンタクトレコードに表示するには、アプリにcrm.objects.contacts.readスコープとcrm.objects.contacts.writeスコープが設定されている必要があります。後でアプリからCRMオブジェクトのスコープを削除する必要が生じたら、まず、それらのオブジェクトタイプを対象とした既存のカードを全て削除する必要があります。

スコープの詳細およびアプリの認証URLの設定については、OAuthのドキュメントを参照してください。

CRMカードを作成する

アプリのCRMカードは、APIを介して作成することも、開発者アカウントでアプリを編集するという方法で作成することもできます。APIを介してカードを設定する方法について詳しくは、この記事の上部にある[エンドポイント]タブをクリックしてご確認ください。

HubSpotのUIを使用してCRMカードを作成するには、次の手順に従います。

    • HubSpot開発者アカウントで、メインナビゲーションにある[アプリ]に移動します。
    • カードを追加する対象のアプリを選択します。
    • 左のサイドバーメニューで[CRMカード]を選択します。
    • 右上の[CRMカードを作成]をクリックします。
      private-app-create-crm-card

以降のセクションで、各タブでの設定オプションについて詳しく説明します。

データリクエスト

HubSpotユーザーが、CRMカードが設定されているCRMレコードを表示すると、HubSpotが連携にデータ取得リクエストを送信します。HubSpotが指定されたターゲットURLに送信するこのリクエストには、一連の既定のクエリーパラメーターの他に、カードの設定として指定されたプロパティーデータを含むパラメーターが追加されます。

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

  • [データ取得URL]フィールドに、データの取得元とするURLを入力します。APIでは、このURLがtargetUrlフィールドに追加されます。 

  • [ターゲット レコード タイプ]セクションで、スイッチをクリックしてオンに切り替え、カードを表示するCRMレコードを選択します。次に、[HubSpotから送信されたプロパティー]ドロップダウンメニューを使用して、リクエストURLにクエリーパラメーターとして含めるHubSpotプロパティーを選択します。APIでは、各レコードタイプおよび対応するプロパティーが、objectTypes配列にオブジェクトとして追加されます。
// Example data fetch configuration { "title": "New CRM Card", "fetch": { "targetUrl": "https://www.example.com/demo-fetch", "objectTypes": [ { "name": "contacts", "propertiesToSend": [ "firstname", "email", "lastname" ] } ] } ... }

リクエストの例

上記の設定により、HubSpotは次のようにGETリクエストを送信します。

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

CRMレコードを読み込んだHubSpotユーザーのID。

userEmail
Default

CRMレコードを読み込んだユーザーのメールアドレス。

associatedObjectId
Default

読み込まれたCRMレコードのID。

associatedObjectType
Default

読み込まれたCRMレコードのタイプ(コンタクト、会社、取引など)。

portalId
Default

CRMレコードを読み込んだHubSpotアカウントのID。

firstname
Custom

[HubSpotから送信されたプロパティー]ドロップダウンメニュー(アプリ内)およびpropertiesToSend配列(API)で指定されたコンタクトの名。

email
Custom

[HubSpotから送信されたプロパティー]ドロップメニュー(アプリ内)およびpropertiesToSend配列(API)で指定されたコンタクトのEメールアドレス。

lastname
Custom

[HubSpotから送信されたプロパティー]ドロップダウンメニュー(アプリ内)およびpropertiesToSend配列(API)で指定されたコンタクトの姓。

注:リクエストは5秒後にタイムアウトになります。そのため、3秒で接続を確立する必要があります。 

レスポンスの例

以下に、インテグレーターが上記のリクエストに対して返すレスポンスの例を示します。

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" } }

リクエスト署名

リクエストが実際にHubSpotから送信されていることを確認するために、リクエストには次のリクエストヘッダーが組み込まれます。このヘッダーには、アプリケーションのアプリシークレットのハッシュとリクエストの詳細が設定されます。

X-HubSpot-Signature:<some base64 string>

この署名を検証するには、次の手順に従います。

  1. 次のように連結した文字列を作成します。<app secret> + <HTTP method> + <URL> + <request body> (if present).
  2. 連結した文字列のSHA-256ハッシュを生成します。
  3. ハッシュ値を署名と比較します。これらが等しい場合、リクエストは検証に合格したことになります。等しくない場合は、リクエストが転送中に改ざんされたか、あるいは他の誰かがエンドポイント宛ての偽装のリクエストを送信している可能性があります。

HubSpotからのリクエストを検証する方法をご確認ください。

カードプロパティー

[カードプロパティー]タブで、HubSpotにCRMカード上に表示させるカスタムプロパティーを定義します。カスタムプロパティー定義すると、連携によってこれらのプロパティーがレスポンスに組み込まれ、値が取り込まれます。

    • [プロパティーを追加]をクリックし、カードに表示する新しいプロパティーを追加します。データ取得呼び出しに対して返すペイロードには、これら全てのプロパティーに値が設定されている必要があります。
    • 右側のパネルで、プロパティーの一意の名前、表示ラベル、データタイプを設定します。データタイプとして、[通貨]、[日付]、[日時]、[Eメール]、[リンク]、[数値]、[ステータス]、[文字列]のいずれかを選択できます。拡張プロパティータイプの使用について詳細をご確認ください。
    • [追加]をクリックしてプロパティーを保存します。
      private-app-create-crm-card-card-properties-tab

HubSpotがデータリクエストを送信すると、連携によって、resultsに含まれる各オブジェクトの他の値に加え、レスポンス内でこれらのプロパティーに値が取り込まれます。このタブで設定されたプロパティーの他に、連携によって独自のカスタムプロパティーが追加される場合もあります。これらのプロパティーをカードの設定で定義する必要はありません。

例えば、以下のレスポンスに含まれるcreatedおよびpriorityは、どちらも[カードプロパティー]タブで定義されたものですが、properties配列では独自のプロパティー定義および値が送信されます。これらのオブジェクト固有のプロパティーは、オブジェクトごとに定義する必要があります。

// 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": [ ... ] }

カスタムプロパティーを送信する際は、各プロパティーのdataTypeフィールドを、CURRENCYDATEDATETIMEEMAILLINKNUMERICSTATUSSTRINGのいずれかに設定できます。プロパティーのタイプによっては、連携で追加のフィールドが必要になる場合があります。以降のセクションで、プロパティーの各タイプについて詳しく説明します。

通貨プロパティー

CURRENCYプロパティーには、currencyCodeを格納する必要があります。このコードは、有効なISO 4217でなければなりません。これにより、ユーザーには正しい通貨記号と数字の書式が表示されます。

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

日付プロパティー

DATEプロパティーは、yyyy-mm-ddの形式でなければなりません。これらのプロパティーは、ユーザーのロケールに適した形式で表示されます。タイムスタンプを含める必要がある場合は、代わりにDATETIMEプロパティーを使用する必要があります。

// 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 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

[カスタムアクション]タブでは、ユーザーがアクションボタンをクリックしたときにリクエストするベースURLを定義できます。CRMカードには、さまざまなアクションに対応する複数のアクションURLを含めることができます。カードのアクションは、このタブで指定されたエンドポイントを呼び出す必要があります。
private-app-create-crm-card-custom-actions-tabアクションフックと確認フックリクエストには、リクエストを検証するためのX-HubSpot-Signatureヘッダーが含まれます。iframeアクションリクエストには、リクエスト署名は含まれません。詳細については、リクエスト署名をご確認ください。

アクションURLは、アクションのuriフィールドでアクセスされます。データ取得リクエストと同様に、アクションフックには一連の既定のクエリーパラメーターが組み込まれます。他のクエリーパラメーターを追加するには、アクションにassociatedObjectPropertiesフィールドを含めます。

レスポンスは、アクションのタイプによって異なります。以下で、アクションのタイプについて詳しく説明します。

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アクションは、ACTION_HOOKアクションと同じように動作しますが、サーバーサイドのリクエストを実行する前にユーザーに確認ダイアログを表示するという点が異なります。X-HubSpot-Signatureヘッダーが検証リクエストに含まれます。リクエスト署名の詳細については、こちらをご覧ください。

// 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" }

httpMethodは、GETPOSTPUTDELETEPATCHのいずれかに設定できます。GETまたはDELETEを使用すると、associatedObjectProperties値がリクエストURLの末尾にクエリーパラメーターとして追加されます。それ以外の場合、プロパティーはリクエスト本文で送信されます。


参考になりましたか?
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。