> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.jp/docs/llms.txt > Use this file to discover all available pages before exploring further. # エンゲージメント | コール export const postmanIcon = ; export const ScopesList = ({scopes = [], description = "この API には、次のいずれかのスコープが必要です。"}) => { if (!scopes || scopes.length === 0) { return null; } const sortedScopes = scopes.sort((a, b) => a.localeCompare(b)); return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
; }; コールエンゲージメントAPIを使用することで、CRMレコードと[コールのインデックスページ](https://knowledge.hubspot.com/ja/records/view-and-filter-records)にコールを記録して管理できます。[HubSpot内でも](https://knowledge.hubspot.com/ja/records/manually-log-activities-on-records)、コールエンゲージメントAPIを使用することでも、コールをログに記録できます。以下にて、APIを使用したコールの基本的な管理方法を説明します。利用可能な全てのエンドポイントとそれぞれの要件については、 [リファレンスドキュメント](/api-reference/crm-calls-v3/guide)でご覧いただけます。 ## コールエンゲージメントを作成する コールエンゲージメントを作成するには、`/crm/v3/objects/calls`に`POST`リクエストを送信します。 リクエストの本文で、**プロパティー**オブジェクト内にコールの詳細を追加します。また、**関連付け**オブジェクトを追加して、新しいコールを既存のレコード（コンタクト、会社など）に関連付けることもできます。 ### プロパティー 以下に、プロパティーオブジェクトに含めることができるHubSpotのデフォルトのコールプロパティーを示します。また、[プロパティーAPI](/api-reference/crm-properties-v3/guide)を使用してカスタムプロパティーを作成することもできます。 | フィールド | 説明 | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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_direction` | HubSpotユーザー側から見たコールの方向。ユーザーがコールの受信者である場合、方向は`INBOUND`に設定されます。ユーザーがコールを開始した場合、方向は`OUTBOUND`に設定されます。 | | `hs_call_disposition` | コールの成果。コールの通話結果を設定するには、内部GUID値を使用する必要があります。アカウントで[カスタムコールの成果](https://knowledge.hubspot.com/ja/calling/create-custom-call-and-meeting-outcomes)が設定されている場合、[このAPI](/api-reference/crm-communications-v3/guide#get-call-engagement-dispositions)を使用してカスタムコール成果に対応する通話結果GUIDを検索できます。既定のHubSpot成果ラベルとそれぞれの内部値は次の通りです。 | | `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` | 通話のソース。これは必須ではありませんが、[録音と文字起こしのパイプライン](/apps/legacy-apps/extensions/calling-extensions/recordings-and-transcriptions#log-a-call-with-your-app-s-endpoint-using-the-engagements-api)を活用する必要があります。プロパティーが設定されている場合は、`INTEGRATIONS_PLATFORM`に設定する必要があります。 | | `hs_call_to_number` | コールを受信した電話番号。 | | `hubspot_owner_id` | コールに関連付けられている[担当者のID](/api-reference/crm-crm-owners-v3/guide)。このフィールドにより、レコードタイムラインでコール作成者としてリストされるユーザーが決まります。 | | `hs_activity_type` | コールのタイプ。利用可能なオプションは、[HubSpotアカウントで設定されたコールタイプ](https://knowledge.hubspot.com/ja/meetings-tool/how-do-i-create-and-use-call-and-meeting-types)に基づきます。 | | `hs_attachment_ids` | コールの添付ファイルのID。複数の添付ファイルIDはそれぞれセミコロンで区切られます。 | ### 関連付け コールを作成して既存のレコードと関連付けるには、リクエストに関連付けオブジェクトを含めます。例えば、コールを作成してコンタクトとチケットに関連付ける場合、リクエスト本文は次のようになります。 ```json theme={null} // 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-reference/crm-associations-v4/guide#association-type-id-values)に記載されています。または、[関連付けAPI](/api-reference/crm-associations-v4/guide#retrieve-association-types)を使用して、カスタム関連付けタイプ（ラベル）の値を取得することもできます。 | コールを一括で作成する方法の詳細については、 [リファレンスドキュメント](/api-reference/crm-calls-v3/guide#post-%2Fcrm%2Fv3%2Fobjects%2Fcalls%2Fbatch%2Fcreate)でご覧いただけます。 ## コールを取得する コールの取得は個別または一括で行うことができます。一括取得の詳細については、[リファレンスドキュメント](/api-reference/crm-calls-v3/guide#post-%2Fcrm%2Fv3%2Fobjects%2Fcalls%2Fbatch%2Fread)でご覧いただけます。 コールIDを指定することで個々のコールを取得するには、`/crm/v3/objects/calls/{callId}`に`GET`リクエストを送信します。リクエストのURLには、次のパラメーターを含めることができます。 | パラメーター | 説明 | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `properties` | 返されるプロパティー[](#call-properties-1)のカンマ区切りリスト。 | | `associations` | 関連するIDの取得対象となるオブジェクトタイプからなるカンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは[関連付けAPI](/api-reference/crm-associations-v4/guide)をご参照ください。 | 全てのコールのリストを要求するには、`/crm/v3/objects/calls`に`GET`リクエストを送信します。リクエストのURLには、次のパラメーターを含めることができます。 | パラメーター | 説明 | | ------------ | ------------------------------------------- | | `limit` | ページごとに表示する結果の最大数。 | | `properties` | 返される[プロパティー](#call-properties-1)のカンマ区切りリスト。 | リクエストが正常に処理されると、レスポンスに`callId`が追加されます。このIDを使用してコールを取得、更新、削除できます。 ## ボイスメールと録音されたコールを識別する 録音されたコールとボイスメールに関しては、レコーディングが`hs_call_recording_url`プロパティーに保存されます。ご使用のアカウントで[インバウンドコール](https://knowledge.hubspot.com/ja/calling/receive-calls-in-hubspot)を利用できる場合、完了して録音されたコールと、ボイスメール付きインバウンドコールを区別するには、リクエストに`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`リクエストを送信します。 リクエストの本文に、更新するコールプロパティーを含めます。 ```json theme={null} //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は、読み取り専用プロパティーおよび存在しないプロパティーの値を無視します。プロパティー値をクリアするには、リクエストの本文でプロパティーの空の文字列を渡します。 一括更新の詳細については、 [リファレンスドキュメント](/api-reference/crm-calls-v3/guide#post-%2Fcrm%2Fv3%2Fobjects%2Fcalls%2Fbatch%2Fupdate)でご覧いただけます。 ### 既存のコールをレコードに関連付ける コールをレコード（コンタクトや、コンタクトに関連付けられている会社など）に関連付けるには、`PUT`リクエストを`/crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`に送信します。リクエストのURLは次のフィールドからなります。 | フィールド | 説明 | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `callId` | コールのID。 | | `toObjectType` | コールに関連付けるオブジェクトのタイプ（コンタクト、会社など）。 | | `toObjectId` | コールに関連付けるレコードのID。 | | `associationTypeId` | コールと他のオブジェクト間の関連付けタイプを示す一意の識別子。このIDは、数値またはスネークケース（例：`call_to_contact`）で表すことができます。[関連付けAPI](/api-reference/crm-associations-v3/guide)を介して値を取得できます。 | 例えば、リクエストの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}` ## レコード上でコールをピン留めする レコードに[コールをピン留め](https://knowledge.hubspot.com/ja/records/pin-an-activity-on-a-record)して、レコードのタイムラインの上部に表示したままにすることができます。ピン留めする前に、コールがすでにレコードに関連付けられている必要があり、1つのレコードにつき1つのアクティビティーのみをピン留めできます。コールをピン留めするには、オブジェクトAPIを介してレコードを作成または更新するときに、`hs_pinned_engagement_id`フィールドにコールの`id`を含めます。[会社](/api-reference/crm-companies-v3/guide#pin-an-activity-on-a-company-record)[、コンタクト](/api-reference/crm-contacts-v3/guide#pin-an-activity-on-a-contact-record)、[取引](/api-reference/crm-deals-v3/guide#pin-an-activity-on-a-deal-record)、[チケット](/api-reference/crm-tickets-v3/guide#pin-an-activity-on-a-ticket-record)、および[カスタムオブジェクト](/api-reference/crm-custom-objects-v3/guide)APIの使用の詳細については、こちらをご覧ください。 ## コールを削除する コールの削除は個別または一括で行うことができます。削除したコールは、HubSpot内のごみ箱に追加されます。そのため、必要に応じて後で[レコードタイムラインからコールを復元](https://knowledge.hubspot.com/ja/records/restore-deleted-activity-in-a-record)することも可能です。 コールIDを指定して個々のコールを削除するには、`DELETE`リクエストを`/crm/v3/objects/calls/{callId}`に送信します。 コールを削除する方法の詳細については、 [リファレンスドキュメント](/api-reference/crm-calls-v3/guide#delete-%2Fcrm%2Fv3%2Fobjects%2Fcalls%2F%7Bcallid%7D)でご覧いただけます。