チケット

概要エンドポイント

HubSpotでは、チケットは顧客からのサポート依頼を表します。チケットは、パイプラインステータスでサポートプロセスを通して、クローズされるまで追跡されます。チケットエンドポイントを使用することにより、チケットレコードを作成および管理したり、HubSpotと他のシステムの間でチケットデータを同期したりできます。 

オブジェクト、レコード、プロパティー、および関連付けAPIの詳細については、「CRMについて」のガイドをご確認ください。HubSpotのオブジェクトとレコードに関する一般的な情報については、CRMデータベースを管理する方法をご確認ください。

チケットを作成する

新しいチケットを作成するには、POSTリクエストを/crm/v3/objects/ticketsに送信します。

リクエスト内のpropertiesオブジェクトにチケットデータを含めます。また、associationsオブジェクトを追加して、新しいチケットを既存のレコード（コンタクト、会社など）やアクティビティー（ミーティング、メモなど）に関連付けることもできます。

プロパティー

チケットの詳細は、チケットプロパティーに保存されます。HubSpotの既定のチケットプロパティーがありますが、カスタムプロパティーを作成することもできます。

新しいチケットを作成する際は、subject（チケット名）およびhs_pipeline_stage（チケットのステータス）を含める必要があります。また、複数のパイプラインがある場合はhs_pipelineも含めます。パイプラインが指定されていない場合は、既定のパイプラインが使用されます。

利用可能な全てのプロパティーを確認するには、GETリクエストを/crm/v3/properties/ticketsに送信して、アカウントのチケットプロパティーのリストを取得します。詳しくはプロパティーAPIをご参照ください。

注：APIを介してチケットを作成するときには、チケットステータスまたはパイプラインの内部IDを使用する必要があります。内部IDは数値であり、APIを介してチケットを取得するときにこれも返されます。チケットステータスまたはパイプラインの内部IDは、チケットパイプライン設定で確認できます。

例えば、新しいチケットを作成する場合、リクエストの内容は次のようになります。

///Example request body { "properties": { "hs_pipeline": "0", "hs_pipeline_stage": "1", "hs_ticket_priority": "HIGH", "subject": "troubleshoot report" } }

関連付け

新しいチケットを作成する際に、そのチケットを既存のレコードやアクティビティーに関連付けることもできます。associationsオブジェクトに、次のフィールドを含めます。

Use this table to describe parameters / fields
ParameterDescription
toObjectId

チケットを関連付けるレコードまたはアクティビティーのID。

associationTypeId

チケットと他のオブジェクトまたはアクティビティーとの関連付けタイプを示す一意の識別子。既定の関連付けタイプはここにリストされています。または、GETリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信して値を取得できます。詳しくは関連付けAPIをご確認ください。

labelフィールドを含めて、関連付けを説明する定義済み関連付けラベルを割り当てることもできます。レコードを関連付ける方法については関連付けAPIをご確認ください。

例えば、新しいチケットを既存のコンタクトと会社に関連付ける場合、リクエストの内容は次のようになります。

///Example request body { "properties": { "hs_pipeline": "0", "hs_pipeline_stage": "1", "hs_ticket_priority": "HIGH", "subject": "troubleshoot report" }, "associations": [ { "to": { "id": 201 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 16 } ] }, { "to": { "id": 301 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 26 } ] }] }

チケットレコードを取得する

チケットを個別に、または一括で取得できます。

  • 個々のチケットを取得するには、GETリクエストを/crm/v3/objects/tickets/{ticketId}に送信します。
  • 全てのチケットのリストを取得するには、GETリクエストを/crm/v3/objects/ticketsに送信します。

これらのエンドポイントに対し、リクエストのURLに次のクエリーパラメーターを含めることができます。 

Use this table to describe parameters / fields
ParameterDescription
properties

レスポンスで取得するプロパティーのカンマ区切りリスト。リクエスト対象のチケットレコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。

propertiesWithHistory

レスポンスで取得する現在および過去のプロパティーのカンマ区切りリスト。リクエスト対象のチケットレコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。

associations

関連付けられているIDが取得されるオブジェクトの、カンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。
  • レコードIDまたはカスタムの固有の識別子のプロパティーを指定して、特定のチケットを一括で取得するには、crm/v3/objects/tickets/batch/readに対してPOSTリクエストを送信します。このバッチエンドポイントは関連付けを取得できません。関連付けAPIを使用してバッチが関連付けを読み取る方法について説明します。

一括読み取りエンドポイントの場合は、任意指定のidPropertyパラメーターを使用し、カスタムの固有の識別子のプロパティーを指定して、チケットを取得することもできます。既定で、リクエストのid値はレコード ID（hs_object_id）を表すので、レコードIDを使用して取得する場合はidPropertyパラメーターは不要です。カスタムの固有の値のプロパティーを使用してチケットを取得する場合は、idPropertyパラメーターを含める必要があります。

例えば、チケットを一括で取得する場合のリクエストは、次のいずれかのようになります。

///Example request body with record ID { "properties": [ "subject", "hs_pipeline_stage", "hs_pipeline" ], "inputs": [ { "id": "4444888856" }, { "id": "666699988" } ] }
///Example request body with a unique value property { "properties": [ "subject", "hs_pipeline_stage", "hs_pipeline" ], "idProperty": "uniquepropertyexample", "inputs": [ { "id": "abc" }, { "id": "def" } ] }

プロパティーの現在の値と過去の値を含むチケットを取得する場合のリクエストは、次のようになります。

///Example request body with record ID (current and historical values) { "propertiesWithHistory": [ "hs_pipeline_stage" ], "inputs": [ { "id": "4444888856" }, { "id": "666699988" } ] }

チケットレコードを更新する

チケットレコードを個別に、または一括で更新できます。既存チケットの場合、APIを介してチケットレコードを更新するために使用可能な一意の値は、チケットIDです。

チケットIDを基準の個々のチケットレコードを更新するには、PATCHリクエストを/crm/v3/objects/tickets/{ticketId}に送信します。リクエストには、更新するデータを含めます。

既存のチケットを他のレコードまたはアクティビティーに関連付ける

チケットを他のCRMレコードまたはアクティビティーに関連付けるには、PUTリクエストを/crm/v3/objects/tickets/{ticketId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。

associationTypeId値を取得するには、この既定値リストを参照するか、GETリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信します。 

詳しくは関連付けAPIをご確認ください。

関連付けを削除する

チケットレコードと他のレコードまたはアクティビティーの関連付けを削除するには、DELETEリクエストを/crm/v3/objects/tickets/{ticketId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。

チケットレコードを削除する

チケットレコードを個別に、または一括で削除できます。削除したチケットレコードは、HubSpot内のごみ箱に追加されます。そのため、必要に応じて後でHubSpot内でチケットレコードを復元できます。

IDを基準に個々のチケットレコードを削除するには、DELETEリクエストを/crm/v3/objects/tickets/{ticketId}に送信します。

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

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