最終更新日: 2025年8月22日

Run in Postman

 コールエンゲージメントAPIを使用することで、CRMレコードとコールのインデックスページにコールを記録して管理できます。HubSpot内でも、コールエンゲージメントAPIを使用することでも、コールをログに記録できます。以下にて、APIを使用したコールの基本的な管理方法を説明します。利用可能な全てのエンドポイントとそれぞれの要件については、 リファレンスドキュメントでご覧いただけます。

​
コールエンゲージメントを作成する

コールエンゲージメントを作成するには、/crm/v3/objects/callsにPOSTリクエストを送信します。 リクエストの本文で、プロパティーオブジェクト内にコールの詳細を追加します。また、関連付けオブジェクトを追加して、新しいコールを既存のレコード（コンタクト、会社など）に関連付けることもできます。

​
プロパティー

以下に、プロパティーオブジェクトに含めることができるHubSpotのデフォルトのコールプロパティーを示します。また、プロパティーAPIを使用してカスタムプロパティーを作成することもできます。
フィールド説明
hs_timestamp必須。このフィールドは、コールの作成時刻を記録し、レコードタイムラインでのそのコールの位置を決定します。ミリ秒単位またはUTC形式のUnixタイムスタンプを使用できます。
hs_call_bodyコールの説明。必要に応じてメモを追加できます。
hs_call_callee_object_idコールに関連付けられているHubSpotレコードのID。OUTBOUNDコールの場合はコールの受信者、INBOUNDコールの場合はコールの発信者になります。
hs_call_callee_object_typeコールに関連付けられているレコードが属するオブジェクトのタイプ（例えば、レコードがコンタクトまたは会社のどちらであるかを指定します）。OUTBOUNDコールの場合は受信者のオブジェクト、INBOUNDコールの場合は発信者のオブジェクトになります。
hs_call_directionHubSpotユーザー側から見たコールの方向。ユーザーがコールの受信者である場合、方向はINBOUNDに設定されます。ユーザーがコールを開始した場合、方向はOUTBOUNDに設定されます。
hs_call_dispositionコールの成果。コールの通話結果を設定するには、内部GUID値を使用する必要があります。アカウントでカスタムコールの成果が設定されている場合、このAPIを使用してカスタムコール成果に対応する通話結果GUIDを検索できます。既定のHubSpot成果ラベルとそれぞれの内部値は次の通りです。
  • 話し中：9d9162e7-6cf3-4944-bf63-4dff82258764
  • 接続済み：f240bbac-87c9-4f6e-bf70-924b57d47db7
  • 伝言を残した：a4c4c377-d246-4b32-a13b-75a56a4cd0ff
  • 留守電を残した：b2cf5968-551e-4856-9783-52b3da59a7d0
  • 応答なし：73a0d17f-1163-4015-bdd5-ec830791da20
  • 番号間違い：17b47fee-58de-441e-a44c-c6300d46f273
hs_call_duration通話時間（ミリ秒）。
hs_call_from_number発信元の電話番号。
hs_call_recording_url通話録音を保存するURL。.mp3ファイルまたは.wavファイルへのURLの場合、CRMレコードで再生できます。HTTPSを使用した安全なURLのみが受け入れられます。
hs_call_statusコールのステータス。ステータスはBUSY、CALLING_CRM_USER、CANCELED、COMPLETED、CONNECTING、FAILED、IN_PROGRESS、NO_ANSWER、QUEUED、およびRINGINGです。
hs_call_title通話のタイトル。
hs_call_source通話のソース。これは必須ではありませんが、録音と文字起こしのパイプラインを活用する必要があります。プロパティーが設定されている場合は、INTEGRATIONS_PLATFORMに設定する必要があります。
hs_call_to_numberコールを受信した電話番号。
hubspot_owner_idコールに関連付けられている担当者のID。このフィールドにより、レコードタイムラインでコール作成者としてリストされるユーザーが決まります。
hs_activity_typeコールのタイプ。利用可能なオプションは、HubSpotアカウントで設定されたコールタイプに基づきます。
hs_attachment_idsコールの添付ファイルのID。複数の添付ファイルIDはそれぞれセミコロンで区切られます。

​
関連付け

コールを作成して既存のレコードと関連付けるには、リクエストに関連付けオブジェクトを含めます。例えば、コールを作成してコンタクトとチケットに関連付ける場合、リクエスト本文は次のようになります。 
// Example request body
{
  "properties": {
    "hs_timestamp": "2021-03-17T01:32:44.872Z",
    "hs_call_title": "Support call",
    "hubspot_owner_id": "11349275740",
    "hs_call_body": "Resolved issue",
    "hs_call_duration": "3800",
    "hs_call_from_number": "(857) 829 5489",
    "hs_call_to_number": "(509) 999 9999",
    "hs_call_recording_url": "https://api.twilio.com/2010-04-01/Accounts/AC890b8e6fbe0d989bb9158e26046a8dde/Recordings/RE3079ac919116b2d22",
    "hs_call_status": "COMPLETED"
  },
  "associations": [
    {
      "to": {
        "id": 500
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 194
        }
      ]
    },
    {
      "to": {
        "id": 1234
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 220
        }
      ]
    }
  ]
}
次のフィールドを関連付けオブジェクトに含める必要があります。
フィールド説明
toコールに関連付けるレコード。一意のid値で指定します。
typesコールとレコード間の関連付けのタイプ。associationCategoryおよびassociationTypeIdを含めます。既定の関連付けタイプIDはこのページに記載されています。または、関連付けAPIを使用して、カスタム関連付けタイプ（ラベル）の値を取得することもできます。
コールを一括で作成する方法の詳細については、 リファレンスドキュメントでご覧いただけます。

​
コールを取得する

コールの取得は個別または一括で行うことができます。一括取得の詳細については、リファレンスドキュメントでご覧いただけます。 コールIDを指定することで個々のコールを取得するには、/crm/v3/objects/calls/{callId}にGETリクエストを送信します。リクエストのURLには、次のパラメーターを含めることができます。
パラメーター説明
properties返されるプロパティーのカンマ区切りリスト。
associations関連するIDの取得対象となるオブジェクトタイプからなるカンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。
全てのコールのリストを要求するには、/crm/v3/objects/callsにGETリクエストを送信します。リクエストのURLには、次のパラメーターを含めることができます。
パラメーター説明
limitページごとに表示する結果の最大数。
properties返されるプロパティーのカンマ区切りリスト。
リクエストが正常に処理されると、レスポンスにcallIdが追加されます。このIDを使用してコールを取得、更新、削除できます。

​
ボイスメールと録音されたコールを識別する

録音されたコールとボイスメールに関しては、レコーディングがhs_call_recording_urlプロパティーに保存されます。ご使用のアカウントでインバウンドコールを利用できる場合、完了して録音されたコールと、ボイスメール付きインバウンドコールを区別するには、リクエストにhs_call_statusおよびhs_call_has_voicemailプロパティーを含めます。 コールでボイスメールが残されている場合、hs_call_statusの値はmissed、hs_call_has_voicemailの値はtrueになります。hs_call_has_voicemailの値は、ボイスメールが残されていないインバウンドコールの場合はfalseに、コールのステータスが不在着信以外の場合はnullになります。

​
コールを更新する

コールを個別に、または一括で更新できます。コールIDを指定して個々のコールを更新するには、/crm/v3/objects/calls/{callId}にPATCHリクエストを送信します。 リクエストの本文に、更新するコールプロパティーを含めます。 
//Example PATCH request to https://api.hubspot.com/crm/v3/objects/calls/{callID}
{
  "properties": {
    "hs_timestamp": "2021-03-17T01:32:44.872Z",
    "hs_call_title": "Discovery call",
    "hubspot_owner_id": "11349275740",
    "hs_call_body": " Decision maker out, will call back tomorrow",
    "hs_call_duration": "3800",
    "hs_call_from_number": "(857) 829 5489",
    "hs_call_to_number": "(509) 999 9999",
    "hs_call_recording_url": "https://api.twilio.com/2010-04-01/Accounts/AC890b8e6fbe0d989bb9158e26046a8dde/Recordings/RE3079ac919116b2d22",
    "hs_call_status": "COMPLETED"
  }
}'
HubSpotは、読み取り専用プロパティーおよび存在しないプロパティーの値を無視します。プロパティー値をクリアするには、リクエストの本文でプロパティーの空の文字列を渡します。 一括更新の詳細については、 リファレンスドキュメントでご覧いただけます。

​
既存のコールをレコードに関連付ける

コールをレコード（コンタクトや、コンタクトに関連付けられている会社など）に関連付けるには、PUTリクエストを/crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。リクエストのURLは次のフィールドからなります。
フィールド説明
callIdコールのID。
toObjectTypeコールに関連付けるオブジェクトのタイプ（コンタクト、会社など）。
toObjectIdコールに関連付けるレコードのID。
associationTypeIdコールと他のオブジェクト間の関連付けタイプを示す一意の識別子。このIDは、数値またはスネークケース（例：call_to_contact）で表すことができます。関連付けAPIを介して値を取得できます。
例えば、リクエストのURLは次のようになります。 https://api.hubspot.com/crm/v3/objects/calls/17591596434/associations/contact/104901/194

​
関連付けを削除する

コールとレコード間の関連付けを削除するには、上記と同じURLにDELETEリクエストを送信します。 /crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

​
レコード上でコールをピン留めする

レコードにコールをピン留めして、レコードのタイムラインの上部に表示したままにすることができます。ピン留めする前に、コールがすでにレコードに関連付けられている必要があり、1つのレコードにつき1つのアクティビティーのみをピン留めできます。コールをピン留めするには、オブジェクトAPIを介してレコードを作成または更新するときに、hs_pinned_engagement_idフィールドにコールのidを含めます。会社、コンタクト、取引、チケット、およびカスタムオブジェクトAPIの使用の詳細については、こちらをご覧ください。

​
コールを削除する

コールの削除は個別または一括で行うことができます。削除したコールは、HubSpot内のごみ箱に追加されます。そのため、必要に応じて後でレコードタイムラインからコールを復元することも可能です。 コールIDを指定して個々のコールを削除するには、DELETEリクエストを/crm/v3/objects/calls/{callId}に送信します。 コールを削除する方法の詳細については、 リファレンスドキュメントでご覧いただけます。