HubSpot API 티켓

HubSpot CRM에서 티켓(ticket)은 고객의 지원 요청을 나타내요. 이 API를 이용하면 티켓 데이터를 만들고 관리하면서 HubSpot과 다른 시스템 간에 동기화할 수 있답니다. 티켓은 지원 프로세스에 따라 파이프라인 상태(pipeline status)를 거치며 관리되고, 문제가 해결되면 닫히게 돼요.

출처: 문서

본문

HubSpot에서 티켓은 고객의 도움 요청을 의미해요. 티켓은 파이프라인 상태로 추적되며 닫힐 때까지 지원 프로세스 안에서 관리되어요. 티켓 엔드포인트를 쓰면 티켓 레코드를 만들고 관리할 수 있고, HubSpot과 다른 시스템 간에 티켓 데이터를 동기화할 수도 있어요. 객체(Object), 레코드, 속성(Property), 연관(Association) API에 대해 더 자세히 알고 싶다면 Understanding the CRM 가이드를 참고하고, HubSpot 내부에서 CRM 데이터베이스를 관리하는 방법도 함께 확인해 보세요.

티켓 만들기 (Create tickets)

새 티켓을 만들려면 /crm/v3/objects/tickets로 POST 요청을 보내요. 요청에 티켓 데이터를 properties 객체로 담아요. 필요하면 associations 객체를 추가해서 새 티켓을 기존 레코드(예: 연락처, 회사)나 활동(예: 미팅, 노트)에 연결할 수도 있어요.

속성 (Properties)

티켓 상세 정보는 티켓 속성에 저장돼요. HubSpot 기본 티켓 속성이 있고, 커스텀 속성도 만들 수 있어요.

새 티켓을 만들 때는 다음 속성을 요청에 포함하는 것이 좋아요.

subject — 티켓의 이름
hs_pipeline_stage — 티켓의 상태
hs_pipeline — 파이프라인이 여러 개인 경우 (지정하지 않으면 기본 파이프라인이 사용돼요)

계정에서 사용 가능한 모든 속성을 확인하려면 /crm/v3/properties/tickets로 GET 요청을 보내면 돼요. 자세한 내용은 properties API 문서를 참고하세요.

참고: API로 티켓을 만들 때는 티켓 상태나 파이프라인의 내부 ID(internal ID)를 사용해야 해요. 내부 ID는 숫자이며 API로 티켓을 조회할 때도 함께 반환돼요. 티켓 상태나 파이프라인의 내부 ID는 티켓 파이프라인 설정에서 찾을 수 있어요.

예를 들어 새 티켓을 만들 때 요청 본문은 다음과 같이 생겼어요.

// 예시 요청 본문
{
  "properties": {
    "hs_pipeline": "0",
    "hs_pipeline_stage": "1",
    "hs_ticket_priority": "HIGH",
    "subject": "troubleshoot report"
  }
}

연관 (Associations)

새 티켓을 만들 때 associations 객체를 넣어 기존 레코드나 활동과 연결할 수도 있어요. 예를 들어 새 티켓을 기존 연락처와 회사에 연결한다면 요청은 다음과 같아요.

{
  "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
        }
      ]
    }
  ]
}

associations 객체에는 다음 값을 포함해야 해요.

파라미터	설명
`to`	티켓과 연결할 레코드나 활동. 고유 `id` 값으로 지정해요.
`types`	티켓과 레코드/활동 사이의 연관 유형. `associationCategory`와 `associationTypeId`를 포함해요. 기본 연관 유형 ID는 이 목록에서 확인할 수 있고, 커스텀 연관 유형(라벨)의 값은 associations API로 조회할 수 있어요.

티켓 조회하기 (Retrieve tickets)

티켓은 개별 또는 일괄로 조회할 수 있어요.

개별 티켓 조회: /crm/v3/objects/tickets/{ticketId}로 GET 요청
전체 티켓 목록 조회: /crm/v3/objects/tickets로 GET 요청

이 엔드포인트에서는 요청 URL에 다음 쿼리 파라미터를 넣을 수 있어요.

파라미터	설명
`properties`	응답에 포함할 속성 목록(쉼표로 구분). 요청한 속성이 정의되지 않았으면 응답에 포함되지 않고, 정의됐지만 티켓에 값이 없으면 `null`로 반환돼요.
`propertiesWithHistory`	응답에 포함할 현재 및 과거 속성 목록(쉼표로 구분). 요청한 속성이 정의되지 않았으면 포함되지 않고, 값이 없으면 `null`로 반환돼요.
`associations`	연관 ID를 가져올 객체 목록(쉼표로 구분). 존재하지 않는 연관은 응답에 포함되지 않아요. 자세한 내용은 associations API를 참고하세요.

레코드 ID나 커스텀 고유 식별 속성으로 특정 티켓들을 일괄 조회하려면 crm/v3/objects/tickets/batch/read로 POST 요청을 보내요. 일괄(batch) 엔드포인트는 연관을 조회할 수 없으니, 연관을 일괄 조회하려면 associations API를 사용하세요.

일괄 조회 엔드포인트에는 선택적으로 idProperty 파라미터를 써서 커스텀 고유 식별 속성으로 티켓을 조회할 수도 있어요. 기본적으로 요청의 id 값은 레코드 ID(hs_object_id)를 가리키므로, 레코드 ID로 조회할 때는 idProperty가 필요 없어요. 커스텀 고유 값 속성으로 조회할 때만 idProperty 파라미터를 포함해야 해요.

예를 들어 티켓을 일괄 조회하려면 다음과 같은 요청을 쓸 수 있어요.

{
  "properties": ["subject", "hs_pipeline_stage", "hs_pipeline"],
  "inputs": [
    {
      "id": "4444888856"
    },
    {
      "id": "666699988"
    }
  ]
}

{
  "properties": ["subject", "hs_pipeline_stage", "hs_pipeline"],
  "idProperty": "uniquepropertyexample",
  "inputs": [
    {
      "id": "abc"
    },
    {
      "id": "def"
    }
  ]
}

속성의 현재 값과 과거 값을 함께 조회하려면 다음과 같이 요청할 수 있어요.

{
  "propertiesWithHistory": ["hs_pipeline_stage"],
  "inputs": [
    {
      "id": "4444888856"
    },
    {
      "id": "666699988"
    }
  ]
}

티켓 수정하기 (Update tickets)

티켓은 개별 또는 일괄로 수정할 수 있어요. 기존 티켓의 경우 레코드 ID가 기본 고유 값이라 API로 티켓을 수정할 때 사용할 수 있고, 커스텀 고유 식별 속성으로도 티켓을 찾아 수정할 수 있어요.

개별 티켓 수정: 레코드 ID로 /crm/v3/objects/tickets/{ticketId}에 PATCH 요청을 보내고, 수정할 데이터를 포함해요.
여러 티켓 수정: /crm/v3/objects/tickets/batch/update에 POST 요청을 보내요. 요청 본문에는 수정할 티켓의 식별자 배열과 수정할 속성을 넣어요.

기존 티켓을 레코드나 활동과 연결하기 (Associate existing tickets)

티켓을 다른 CRM 레코드나 활동에 연결하려면 /crm/v3/objects/tickets/{ticketId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}에 PUT 요청을 보내요.

associationTypeId 값을 가져오려면 기본 값 목록을 참조하거나 /crm/v4/associations/{fromObjectType}/{toObjectType}/labels로 GET 요청을 보내면 돼요. 자세한 내용은 associations API를 참고하세요.

연관 제거하기 (Remove an association)

티켓과 레코드나 활동 사이의 연관을 제거하려면 다음 URL에 DELETE 요청을 보내요.

/crm/v3/objects/tickets/{ticketId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

티켓 레코드에 활동 고정하기 (Pin an activity)

hs_pinned_engagement_id 필드에 고정할 활동의 id를 넣어 티켓 레코드에 활동을 고정할 수 있어요. 활동 id는 engagements API로 조회할 수 있어요. 레코드당 활동 하나만 고정할 수 있고, 고정하기 전에 활동이 이미 티켓에 연결되어 있어야 해요.

티켓의 고정 활동을 설정하거나 변경하려면 다음과 같이 요청할 수 있어요.

{
  "properties": {
    "hs_pinned_engagement_id": 123456789
  }
}

한 번의 요청으로 티켓을 만들고 기존 활동과 연결한 뒤 그 활동을 고정할 수도 있어요. 예를 들면:

{
  "properties": {
    "hs_pipeline": "0",
    "hs_pipeline_stage": "1",
    "hs_ticket_priority": "HIGH",
    "subject": "troubleshoot report",
    "hs_pinned_engagement_id": 123456789
  },
  "associations": [
    {
      "to": {
        "id": 123456789
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 227
        }
      ]
    }
  ]
}

티켓 삭제하기 (Delete tickets)

티켓은 개별 또는 일괄로 삭제할 수 있어요. 삭제된 티켓은 HubSpot의 휴지통(recycling bin)에 들어가고, 나중에 HubSpot 내에서 복원할 수 있어요.

개별 티켓 삭제: ID로 /crm/v3/objects/tickets/{ticketId}에 DELETE 요청을 보내요.

더 알아보기 (Learn more)

공식 문서