コール

概要エンドポイント

コールエンゲージメントAPIを使用することで、CRMレコードとコール インデックス ページにコールを記録して管理できます。HubSpotでも、コールエンゲージメントAPIを使用することでも、コールをログに記録できます。この記事では、APIを使用したコールの基本的な管理方法を説明します。利用可能な全てのエンドポイントとそれぞれの要件を確認するには、記事の上部にある［エンドポイント］タブをクリックしてください。

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

コールエンゲージメントを作成するには、/crm/v3/objects/callsにPOSTリクエストを送信します。

リクエストの本文で、propertiesオブジェクト内にコールの詳細を追加します。associationsオブジェクトを追加して、新しいコールを既存のレコード（コンタクト、会社など）に関連付けることもできます。

プロパティー

propertiesオブジェクトには、次のフィールドを含めることができます。

Use this table to describe parameters / fields
フィールドDescription
hs_timestamp

必須。このフィールドは、コールの作成時刻を記録し、レコードタイムラインでのそのコールの位置を決定します。ミリ秒単位またはUTC形式のUnixタイムスタンプを使用できます。 

hs_call_body

コールの説明。必要に応じてメモを追加できます。

hs_call_callee_object_id

コールに関連付けられているHubSpotレコードのID。OUTBOUNDコールの場合はコールの受信者、INBOUNDコールの場合はコールの発信者になります。

hs_call_callee_object_type_id

コールに関連付けられているレコードが属するオブジェクトのID（例えば、レコードがコンタクトまたは会社であるかを指定します）。OUTBOUNDコールの場合は受信者のオブジェクト、INBOUNDコールの場合は発信者のオブジェクトになります。

hs_call_direction

HubSpotユーザーの視点から見たコールの方向。ユーザーがコールの受信者である場合、方向は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はそれぞれセミコロンで区切られます。

関連付け

コールを作成して既存のレコードと関連付けるには、リクエストにassociationsオブジェクトを含めます。このオブジェクトには、次のフィールドを含める必要があります。

Use this table to describe parameters / fields
フィールドDescription
toObjectId

コールに関連付けるレコードのID。

associationType

コールと他のオブジェクトとの関連付けタイプを示す一意の識別子。このIDは、数値またはスネークケース（call_to_contact）で表すことができます。該当する値は関連付けAPIを介して取得できます。

例えば、コールを作成してコンタクトとチケットに関連付ける場合、リクエスト本文は次のようになります。

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

コールを一括で作成する方法については、この記事の上部にある［エンドポイント］をクリックしてください。

コールを取得する

コールを個別に、または一括で取得できます。コールを一括で取得する方法については、この記事の上部にある［エンドポイント］をクリックしてください。

コールIDを指定して個々のコールを取得するには、/crm/v3/objects/calls/{callId}にGETリクエストを送信します。リクエストのURLには、次のパラメーターを含めることができます。 

Use this table to describe parameters / fields
ParameterDescription
properties

返されるプロパティーごとにカンマで区切られたリスト。 

associations

関連付けられているIDを取得するオブジェクトのタイプごとにカンマで区切られたリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご確認ください。

全てのコールのリストを要求するには、/crm/v3/objects/callsにGETリクエストを送信します。リクエストのURLには、次のパラメーターを含めることができます。 

Use this table to describe parameters / fields
ParameterDescription
limit

ページごとに表示する結果の最大数。

properties

返されるプロパティーごとにカンマで区切られたリスト。 

リクエストが正常に完了すると、レスポンスにcallIdが追加されます。このIDを使用して、対応するコールを取得、更新、削除できます。 

Identify voicemails vs. recorded calls

録音された通話やボイスメールの場合、録音は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になり、コースのステータスがmissed以外の場合は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は次のフィールドからなります。

Use this table to describe parameters / fields
フィールドDescription
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}に送信します。

コールを一括で削除する方法については、この記事の上部にある［エンドポイント］をクリックしてください。

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