CRMカード
公開アプリ内でカスタムCRMカードを作成し、HubSpotのコンタクト、会社、取引、チケットのレコードに他のシステムからの情報を表示できます。各アプリには、最大25枚のCRMカードを含めることができます。
使用例:アプリマーケットプレイスに掲載する、バグ追跡用ソフトウェアの連携を構築しています。サポート担当者がユーザーに対応する際に参照できるよう、コンタクトレコードに追跡対象のバグが表示されるようにしたいと考えています。この情報は、貴社のアプリにカスタムカードを定義することで、HubSpotコンタクトレコード上に表示できます。カードはアプリの機能設定の一部として定義できます。アプリをインストールしたユーザーがターゲットのCRMレコードを表示すると、HubSpotはアプリにリクエストを送信して関連するデータを取得し、レコードページ上のカードにそのデータを表示します。アプリには、この情報に基づいてユーザーが実行できるカスタムアクションを指定することもできます。例えば、HubSpot内でアプリ独自のUIを表示するためのモーダルを開くアクションをアプリに組み込むことができます。
カスタムCRMカードを作成するアプリは、カードを表示するCRMレコードの変更に必要なOAuthスコープをリクエストする必要があります。例えば、CRMカードをコンタクトレコードに表示するには、アプリにcrm.objects.contacts.read
スコープとcrm.objects.contacts.write
スコープが設定されている必要があります。後でアプリからCRMオブジェクトのスコープを削除する必要が生じたら、まず、それらのオブジェクトタイプを対象とした既存のカードを全て削除する必要があります。
スコープの詳細およびアプリの認証URLの設定については、OAuthのドキュメントを参照してください。
アプリのCRMカードは、APIを介して作成することも、開発者アカウントでアプリを編集するという方法で作成することもできます。APIを介してカードを設定する方法について詳しくは、この記事の上部にある[エンドポイント]タブをクリックしてご確認ください。
HubSpotのUIを使用してCRMカードを作成するには、次の手順に従います。
- HubSpot開発者アカウントで、メインナビゲーションにある[アプリ]に移動します。
- カードを追加する対象のアプリを選択します。
- 左のサイドバーメニューで[CRMカード]を選択します。
- 右上の[CRMカードを作成]をクリックします。
以降のセクションで、各タブでの設定オプションについて詳しく説明します。
HubSpotユーザーが、CRMカードが設定されているCRMレコードを表示すると、HubSpotが連携にデータ取得リクエストを送信します。HubSpotが指定されたターゲットURLに送信するこのリクエストには、一連の既定のクエリーパラメーターの他に、カードの設定として指定されたプロパティーデータを含むパラメーターが追加されます。
-
[データ取得URL]フィールドに、データの取得元とするURLを入力します。APIでは、このURLが
targetUrl
フィールドに追加されます。 - [ターゲット レコード タイプ]セクションで、スイッチをクリックしてオンに切り替え、カードを表示するCRMレコードを選択します。次に、[HubSpotから送信されたプロパティー]ドロップダウンメニューを使用して、リクエストURLにクエリーパラメーターとして含めるHubSpotプロパティーを選択します。APIでは、各レコードタイプおよび対応するプロパティーが、
objectTypes
配列にオブジェクトとして追加されます。
上記の設定により、HubSpotは次のようにGET
リクエストを送信します。
Parameter | Type | Description |
---|---|---|
userId
| Default | CRMレコードを読み込んだHubSpotユーザーのID。 |
userEmail
| Default | CRMレコードを読み込んだユーザーのメールアドレス。 |
associatedObjectId
| Default | 読み込まれたCRMレコードのID。 |
associatedObjectType
| Default | 読み込まれたCRMレコードのタイプ(コンタクト、会社、取引など)。 |
portalId
| Default | CRMレコードを読み込んだHubSpotアカウントのID。 |
firstname
| Custom | [HubSpotから送信されたプロパティー]ドロップダウンメニュー(アプリ内)および |
email
| Custom | [HubSpotから送信されたプロパティー]ドロップメニュー(アプリ内)および |
lastname
| Custom | [HubSpotから送信されたプロパティー]ドロップダウンメニュー(アプリ内)および |
注:リクエストは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 |
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. |
リクエストが実際にHubSpotから送信されていることを確認するために、リクエストには次のリクエストヘッダーが組み込まれます。このヘッダーには、アプリケーションのアプリシークレットのハッシュとリクエストの詳細が設定されます。
X-HubSpot-Signature:<some base64 string>
この署名を検証するには、次の手順に従います。
- 次のように連結した文字列を作成します。
<app secret>
+<HTTP method>
+<URL>
+<request body> (if present)
. - 連結した文字列のSHA-256ハッシュを生成します。
- ハッシュ値を署名と比較します。これらが等しい場合、リクエストは検証に合格したことになります。等しくない場合は、リクエストが転送中に改ざんされたか、あるいは他の誰かがエンドポイント宛ての偽装のリクエストを送信している可能性があります。
[カードプロパティー]タブで、HubSpotにCRMカード上に表示させるカスタムプロパティーを定義します。カスタムプロパティー定義すると、連携によってこれらのプロパティーがレスポンスに組み込まれ、値が取り込まれます。
-
- [プロパティーを追加]をクリックし、カードに表示する新しいプロパティーを追加します。データ取得呼び出しに対して返すペイロードには、これら全てのプロパティーに値が設定されている必要があります。
- 右側のパネルで、プロパティーの一意の名前、表示ラベル、データタイプを設定します。データタイプとして、[通貨]、[日付]、[日時]、[Eメール]、[リンク]、[数値]、[ステータス]、[文字列]のいずれかを選択できます。拡張プロパティータイプの使用について詳細をご確認ください。
- [追加]をクリックしてプロパティーを保存します。
HubSpotがデータリクエストを送信すると、連携によって、results
に含まれる各オブジェクトの他の値に加え、レスポンス内でこれらのプロパティーに値が取り込まれます。このタブで設定されたプロパティーの他に、連携によって独自のカスタムプロパティーが追加される場合もあります。これらのプロパティーをカードの設定で定義する必要はありません。
例えば、以下のレスポンスに含まれるcreated
およびpriority
は、どちらも[カードプロパティー]タブで定義されたものですが、properties
配列では独自のプロパティー定義および値が送信されます。これらのオブジェクト固有のプロパティーは、オブジェクトごとに定義する必要があります。
カスタムプロパティーを送信する際は、各プロパティーのdataType
フィールドを、CURRENCY
、DATE
、DATETIME
、EMAIL
、LINK
、NUMERIC
、STATUS
、STRING
のいずれかに設定できます。プロパティーのタイプによっては、連携で追加のフィールドが必要になる場合があります。以降のセクションで、プロパティーの各タイプについて詳しく説明します。
CURRENCY
プロパティーには、currencyCode
を格納する必要があります。このコードは、有効なISO 4217でなければなりません。これにより、ユーザーには正しい通貨記号と数字の書式が表示されます。
DATE
プロパティーは、yyyy-mm-dd
の形式でなければなりません。これらのプロパティーは、ユーザーのロケールに適した形式で表示されます。タイムスタンプを含める必要がある場合は、代わりに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
リクエストには
X-HubSpot-Signature
ヘッダーが含まれます。
アクションURLは、アクションのuri
フィールドでアクセスされます。データ取得リクエストと同様に、アクションフックには一連の既定のクエリーパラメーターが組み込まれます。他のクエリーパラメーターを追加するには、アクションにassociatedObjectProperties
フィールドを含めます。
レスポンスは、アクションのタイプによって異なります。以下で、アクションのタイプについて詳しく説明します。
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.
CONFIRMATION_ACTION_HOOK
アクションは、ACTION_HOOK
アクションと同じように動作しますが、サーバーサイドのリクエストを実行する前にユーザーに確認ダイアログを表示するという点が異なります。
httpMethod
は、GET
、POST
、PUT
、DELETE
、PATCH
のいずれかに設定できます。GET
またはDELETE
を使用すると、associatedObjectProperties
値がリクエストURLの末尾にクエリーパラメーターとして追加されます。それ以外の場合、プロパティーはリクエスト本文で送信されます。
貴重なご意見をありがとうございました。