CRMカード

カスタムCRMカードは、他のシステムからの情報をHubSpotのコンタクト、会社、取引、またはチケットレコードに表示できる仕組みです。この機能を使用すると、他のシステムからのデータを表示するカスタムカードをアプリ上に作成できます。HubSpot上にデータを格納にする際に、ニーズを満たせるネイティブオブジェクトがない場合は、カスタムオブジェクト(英語)によってニーズを満たせるかどうかを検討してみてください。

使用例:エンジニアリングチームはあるソフトウェアサービスを使用して不具合を追跡していますが、カスタマーサービス担当者はHubSpotを使用しています。カスタマーサービス担当者はHubSpotを離れることなく、顧客からの不具合情報を確認したいと考えています。この情報は、貴社のアプリにカスタムカードを定義することで、HubSpotコンタクトレコード上に表示できます。

仕組み

カードはアプリの機能設定の一部として定義できます。アプリをインストールしたユーザーがターゲットのCRMレコードを表示すると、HubSpotはアプリにリクエストを送信して関連するデータを取得し、レコードページ上のカード内にそのデータを表示します。アプリには、この情報に基づいてユーザーが実行できるカスタムアクションを指定することもできます。カスタムアクションの一例として、アプリ独自のユーザーインターフェイス(UI)をモーダルとしてHubSpot上に表示するアクションが考えられます。

CRMカードの例を以下に示します。

CRM_Card_1

また、CRM上にカードのプロパティーを表示する場合のデータフローの例(英語)を以下に示します。

CRM_card_diagram

 

CRMカードを設定する

CRMカードの作成と設定には開発者アカウントを使用します。カード内の項目は、カードプロパティーとして表されます。このプロパティーのタイトルを(必要に応じて)インテグレーターの外部システムに合わせておくことができます。

アプリダッシュボードで、カードを追加するアプリを選択し、CRMカードに進みます。[CRMカードを作成]ボタンをクリックして作成を開始します。

Screen Shot 2020-01-14 at 7.36.35 PM

スコープの要件

カスタムCRMカードを作成するアプリは、カードを表示するCRMレコードの変更に必要なOAuthスコープをリクエストする必要があります。つまり、コンタクト、会社、または取引のカードを設定するためのcontactsスコープと、チケットのカードを設定するためのticketsスコープをリクエストします。

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

スコープを削除する

アプリですでにCRMカードを使用している場合、そのオブジェクトタイプに関連付けられているすべての既存カードを削除するまでは、contactsスコープもticketsスコープも削除できません。

 

新規カードを作成する

CRMカードを使用するための最初のステップは、カードテンプレートの作成です。ユーザーには、以下の内容が表示されます。

CRM_card_2

 

APIを使用してカードを設定する

APIを使用してカードを管理する方法は、このページの「エンドポイント」タブをご覧ください。

アプリ設定UIを使用してカードを設定する

開発者アカウントのアプリの機能設定からCRMカードを作成、管理*することもできます(前述の手順を参照)。

Example_CRM_card_3

*1つのアプリにつき、最大25件のCRMカードを作成できます。


関連ドキュメント

CRMについて

タイムラインイベント

データ フェッチ リクエスト

「概要」タブにある説明のように、アプリに関連付けられているCRMレコードをユーザーが表示するたびに、HubSpotからそのアプリにデータフェッチ(取得)リクエストが送信されます。これらのリクエストは、ペイロードとして該当するCRMレコードの詳細を付けて、カードに指定されているfetch/targetUrlに送信されます。

レスポンスには最大5つのカードプロパティーを含めることができます。特定のCRMオブジェクトにこれよりも多くのプロパティーがある場合は、アプリからそれらのプロパティーにリンクできます。

リクエストは5秒でタイムアウトすることに注意してください。そのため、3秒で接続を確立する必要があります。 

データ フェッチ リクエストの例:

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

 
ヘッダーの内容:
X-HubSpot-Signature: <some base64 string>

X-HubSpot-Signatureヘッダーを使用して、リクエストがHubSpotから送信されていることを確認できます。詳細については、リクエストの署名(英語)を参照してください。

クエリーパラメーター:
  • userId:データをリクエストしている顧客の数値形式のユーザーID。
  • userEmail:データをリクエストしているHubSpotユーザーのEメールアドレス。
  • associatedObjectId:現在のオブジェクトのID。associatedObjectTypeによってIDのタイプは異なります。チケットの場合は、companyIddealIdcontact vIDobjectIdのいずれかです。
  • associatedObjectType:ユーザーがリクエストしているデータのオブジェクトタイプ(contactcompanydeal、またはticket)。これは、このレコードタイプに指定されている associatedHubSpotObjectTypesのいずれかです。
  • また、リクエストされたいずれかのassociatedHubSpotObjectTypePropertiesの値です。リクエストされたプロパティーのいずれかが現在のオブジェクトで定義されていない場合、そのプロパティーはクエリー文字列に含められません。上記の例には、会社プロパティーとしてdomainが含まれています。下のスクリーンショットに示されているように、リクエストのプロパティーはアプリ設定UIで定義できます。 

Associated_Objects

レスポンスの例:
JSON
// 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"
  }
}
定義:
  • results:最大5個の有効なカードプロパティーのリスト。 
  • results[].objectId:このオブジェクトの固有ID。このプロパティーは必須です。
  • results[].title:このオブジェクトのタイトル。このプロパティーは必須です。
  • results[].link:ユーザーがこのオブジェクトに関する詳細を取得するために使用できるURI。任意のプロパティーですが、どのオブジェクトにもリンクがない場合は、値としてnullを指定してください。
  • results[].properties:カード設定に定義されていないカスタムプロパティーのリスト。このリストを使用して、特定のオブジェクトに固有のプロパティーを表示することができます。これらのプロパティーは、カード設定で定義されたプロパティーの後に、提示した順に示されます。任意のプロパティーです。
  • results[].actions:このオブジェクトに対してユーザーが実行できるアクションのリスト。アクションの指定については、アクションタイプを参照してください。任意のプロパティーです。
  • totalCount:リクエストしたCRMオブジェクトに関連付けられているカードプロパティーの数が5個を超える場合に、使用可能なプロパティーの合計数。任意のプロパティーです。
  • allItemsLink:リクエストしたCRMオブジェクトに関連付けられているカードプロパティーの数が5個を超える場合に、そのすべてのプロパティーを示すURI。任意のプロパティーです。
  • itemLabel:「さらに表示」リンクなどで使用されるラベル(例:「チケットをさらに表示」)。任意のプロパティーです。指定がない場合、既定でカードのタイトルが使用されます。
  • settingsAction:ユーザーがアプリの設定を更新するために使用できるiframeアクション。アクションの指定については、アクションタイプを参照してください。任意のプロパティーです。
  • primaryAction:レコードタイプのプライマリーアクション(通常は「作成」アクション)。アクションの指定については、アクションタイプを参照してください。任意のプロパティーです。
  • secondaryActions:カードレベルに表示されるアクションのリスト。アクションの指定については、アクションタイプを参照してください。任意のプロパティーです。

上記のプロパティーに加えて、インテグレーターはカード設定で定義されているプロパティーの値を指定できます。上記の例のJSONプロパティーcreatedでは、

"created":"2016-08-04"

このオブジェクトにあらかじめ定義されているcreatedプロパティーの値が返されます。

CRM_card_5

アクションフックを処理する 

アクションフックとして定義されているアクションをユーザーがクリックすると、HubSpotから、アクション定義に指定されているURIとHTTPメソッドを使用してリクエストが送信されます。

リクエストの例:

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

ヘッダーの内容:
X-HubSpot-Signature: <some base64 string>
クエリーパラメーター:
  • userId:データをリクエストしている顧客の数値形式のユーザーID。
  • userEmail:データをリクエストしている顧客のHubSpotユーザーEメールアドレス。
  • associatedObjectId:現在のオブジェクトのID。associatedObjectTypeによってIDのタイプは異なります。チケットの場合は、companyIddealIdcontact vidobjectIdのいずれかです。
  • associatedObjectType:ユーザーがリクエストしているデータのオブジェクトタイプ(contactcompanydeal、または ticket)。
  • portalId:データをリクエストしている顧客のアカウントID(Hub IDとも呼ばれます)。
  • また、リクエストされたいずれかのassociatedObjectPropertiesの値です。リクエストされたプロパティーのいずれかが現在のオブジェクトに定義されていない場合、そのプロパティーはクエリー文字列に含められません。上記の例には、会社プロパティーとしてdomainが含まれています。

インテグレーターはリクエストがHubSpotから送信されたことを確認するために、X-HubSpot-Signatureヘッダーを使用できます。詳細については、リクエストの署名(英語)を参照してください。

レスポンスの例:
{"message":"Successfully deleted object"}

HubSpotは、アクションフックに対するレスポンスをJSONとして解析してメッセージプロパティーを検索しようと試みます。ユーザーには、成功または失敗のいずれかのメッセージが表示されます。

レスポンスのステータスコードが2XXの場合は成功メッセージが表示され、4XXまたは5XXの場合はエラーメッセージが表示されます。

 

アクションタイプ

ここでは、指定できるアクションの各タイプについて説明します。

iframeアクション

ユーザーがiframeアクションをクリックすると、そのiframeで指定されているURLにあるモーダルダイアログが開きます。

iframeアクションの例:
JSON
//
{
  "type": "IFRAME",
  "width": 890,
  "height": 748,
  "uri": "https://example.com/iframe- contents",
  "label": "Edit",
  "associatedObjectProperties": [
    "some_crm_property"
  ]

}
定義:
  • type:iframeアクションであることを示すIFRAMEを指定します。
  • width, height:目的のiframeサイズ。
  • uri:iframeで開くURI。
  • label:アクションドロップダウンに表示されるラベル。
  • associatedObjectProperties:関連付けられているコンタクト、会社、取引、またはチケットのプロパティーのリスト。Iframeを開く際に、現在のオブジェクトのプロパティー値がクエリーパラメーターとしてURLに付加されます。

モーダルを閉じるための信号

ユーザーがiframeアクションを完了したら、モーダルダイアログを閉じて、ユーザーを元のCRM画面にリダイレクトする必要があります。ダイアログモデルを閉じるには、アプリでwindow.postMessageメッセージを使用できます。次のメッセージを使用できます。

  • {"action":"DONE"} - ユーザーが正常にアクションを完了しました。
  • {"action":"CANCEL"} -ユーザーがアクションをキャンセルしました。
例:window.parent.postMessage(JSON.stringify({"action":"DONE"}), "*");

:iframeアクションによってアクセスされたiframeモーダルは、レスポンシブな幅に設定されます。 

 

アクションフックのアクション

アクションフックのアクションにより、サーバーサイドのリクエストがアプリに送信されます。このアクションでユーザーに表示されるUIは、成功メッセージまたはエラーメッセージのみです。このタイプのアクションは、ユーザー入力を必要としないシンプルな操作に役立ちます。

アクションフックのアクションの例:
JSON
//
{
  "type": "ACTION_HOOK",
  "httpMethod": "POST",
  "uri": "https://example.com/action-hook",
  "label": "Example action",
  "associatedObjectProperties": [
    "some_crm_property"
  ]
}
定義:
  • type:アクションフックのアクションであることを示すACTION_HOOKを指定します。
  • httpMethod:リクエストに使用するHTTPメソッド。GETPOSTPUTDELETEPATCHのいずれかです。
  • uri:リクエストの送信先URI。
  • label:アクションドロップダウンに表示するラベル。
  • associatedObjectProperties:関連付けられているコンタクト、会社、取引、またはチケットのプロパティーのリスト。httpMethodGETまたはDELETEの場合、これらのプロパティー値がクエリーパラメーターとしてリクエストのURIに付加されます。それ以外の場合は、JSONリクエスト本文として送信されます。

アクションエンドポイントの実装方法については、アクションフックの処理を参照してください。

確認アクション

確認アクションは、アクションフックと同様に動作しますが、サーバーサイドのリクエストを実行する前にユーザーに確認ダイアログが表示される点が異なります。

 

JSON
// {
  "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"
}
定義:
  • type:アクションフックのアクションであることを示すACTION_HOOKを指定します。
  • httpMethod:リクエストに使用するHTTPメソッド。GETPOSTPUTDELETEPATCHのいずれかです。
  • uri:リクエストの送信先URI。
  • label:アクションドロップダウンに表示するラベル。
  • associatedObjectProperties:関連付けられているコンタクト、会社、取引、またはチケットのプロパティーのリスト。httpMethodGETまたはDELETEの場合、これらのプロパティー値がクエリーパラメーターとしてリクエストのURIに付加されます。それ以外の場合は、JSONリクエスト本文として送信されます。

アクションエンドポイントの実装方法については、アクションフックの処理を参照してください。

確認アクション

確認アクションは、アクションフックと同様に動作しますが、サーバーサイドのリクエストを実行する前にユーザーに確認ダイアログが表示される点が異なります。

定義:
  • type:確認アクションのフックアクションであることを示すCONFIRMATION_ACTION_HOOKを指定します。
  • httpMethod:リクエストに使用するHTTPメソッド。GETPOSTPUTDELETEPATCHのいずれかです。
  • uri:リクエストの送信先URI。
  • label:アクションドロップダウンに表示するラベル。
  • associatedObjectProperties:関連付けられているコンタクト、会社、取引、またはチケットのプロパティーのリスト。httpMethodGETまたはDELETEの場合、これらのプロパティー値がクエリーパラメーターとしてリクエストのURIに付加されます。それ以外の場合は、JSONリクエスト本文として送信されます。
  • confirmationMessage:ユーザーへの確認ダイアログに表示するメッセージ。
  • confirmButtonText:OKボタンのテキスト。任意。既定では、ボタンのテキストは[OK]に設定されます。
  • cancelButtonText:キャンセルボタンのテキスト。任意。既定では、ボタンのテキストは[キャンセル]に設定されます。

アクションエンドポイントの実装方法については、アクションフックの処理を参照してください。


参考になりましたか? *
こちらのフォームには開発者向けドキュメントに関するご意見をお聞かせください。なお、HubSpot製品に関するご意見は、アイデアフォーラム(英語)にお寄せください。