Freshdesk API 그룹

Freshdesk의 그룹(Group)은 에이전트들을 묶어서 한 종류의 문제에 집중하게 해주는 기능이에요. 예를 들어 "결제 문의", "기술 지원"처럼 팀을 나누고, 그 팀이 반복되는 문제와 고객에 더 잘 대응하도록 돕죠. 이번 글에서는 Freshdesk API로 그룹을 생성하고 조회하는 방법, 그리고 티켓을 자동으로 배정하거나 에스컬레이션하는 설정까지 차근차근 살펴볼게요.

출처: Freshdesk API 문서

본문

그룹 API는 크게 두 종류가 있어요. 하나는 오래된 Group API(/api/v2/groups)이고, 다른 하나는 더 많은 기능을 갖춘 새 Group API(/api/v2/admin/groups)예요. 이번에는 우선 기본이 되는 그룹 API를 중심으로 다뤄볼게요. 참고로 그룹 API는 관리자(admin) 권한이 있는 사용자만 호출할 수 있어요.

그룹 속성(Attribute)

그룹을 만들거나 조회할 때 다루는 주요 속성들은 다음과 같아요.

속성	타입	설명
`agent_ids`	array	그룹에 속한 에이전트 사용자 ID 배열 (콤마로 구분)
`auto_ticket_assign`	number	자동 티켓 배정 방식의 종류 (아래 표 참고)
`business_hour_id`	number	그룹과 연결된 업무 시간(business hour)의 고유 ID
`description`	string	그룹 설명
`escalate_to`	number	티켓이 배정되지 않았을 때 에스컬레이션 이메일을 받을 사용자 ID. '없음'으로 설정하려면 `null`을 넣어요
`id`	number	그룹의 고유 ID
`name`	string	그룹 이름
`unassigned_for`	string	티켓이 배정되지 않은 채 일정 시간이 지나면 에스컬레이션 이메일을 보내요. 허용 값은 `"30m"`, `"1h"`, `"2h"`, `"4h"`, `"8h"`, `"12h"`, `"1d"`, `"2d"`, `"3d"` (기본값 `"30m"`)
`created_at`	datetime	그룹 생성 시각
`updated_at`	datetime	그룹 수정 시각

자동 티켓 배정(Automatic Ticket Assignment) 값

그룹마다 자동 티켓 배정 방식을 고정된 숫자 값(auto_ticket_assign)으로 표현해요.

배정 방식	값
Disabled (사용 안 함)	`0`
Round Robin (라운드 로빈)	`1`
Skill Based Round Robin (스킬 기반 라운드 로빈)	`2`
Load Based Round Robin (부하 기반 라운드 로빈)*	`3`
Omniroute	`12`

> Load Based Round Robin은 Omniroute로 업그레이드되고 있어요.

그룹 생성하기

POST /api/v2/groups 로 그룹을 생성해요. name은 필수(Mandatory)이며 유일(Unique)해야 해요.

샘플 코드 (Curl)

curl -v -u yourapikey:*** -H "Content-Type: application/json" -X POST -d '{
  "name":"Entertainment",
  "description":"Singers and dancers",
  "unassigned_for":"30m",
  "agent_ids":[1,16]
}' 'https://domain.freshdesk.com/api/v2/groups'

요청(Request) 본문

{
  "name":"Entertainment",
  "description":"Singers and dancers",
  "unassigned_for":"30m",
  "agent_ids":[1,16],
  "escalate_to":1
}

응답(Response)

{
  "id":5,
  "name":"Entertainment",
  "description":"Singers and dancers",
  "business_hour_id":null,
  "escalate_to":1,
  "unassigned_for":"30m",
  "agent_ids":[1,16],
  "auto_ticket_assign":0,
  "created_at":"2014-01-08T07:53:41+05:30",
  "updated_at":"2014-01-08T07:53:41+05:30"
}

생성 시 auto_ticket_assign을 명시하지 않으면 기본값 0(Disabled)으로 설정돼요. 계정이 자동 티켓 배정을 지원하는 플랜이 아니라면 이 값은 무시돼요. escalate_to를 '없음'(none)으로 만들고 싶다면 요청 본문에 null을 넣으면 돼요.

그룹 조회하기

단일 그룹 조회 — GET /api/v2/groups/[id]

curl -v -u yourapikey:*** -X GET 'https://domain.freshdesk.com/api/v2/groups/1'

응답(Response)

{
  "id":1,
  "name":"Entertainers",
  "description":"Singers dancers and stand up comedians",
  "business_hour_id":null,
  "escalate_to":1,
  "unassigned_for":"30m",
  "agent_ids":[2,15],
  "auto_ticket_assign":0,
  "created_at":"2014-01-08T07:53:41+05:30",
  "updated_at":"2014-01-08T07:53:41+05:30"
}

전체 그룹 조회 — GET /api/v2/groups

curl -v -u yourapikey:*** -X GET 'https://domain.freshdesk.com/api/v2/groups'

응답(Response) — 배열로 반환돼요.

[
  {
    "id":1,
    "name":"Entertainers",
    "description":"Singers dancers and stand up comedians",
    "business_hour_id":null,
    "escalate_to":1,
    "unassigned_for":"30m",
    "auto_ticket_assign":0,
    "created_at":"2014-01-08T07:53:41+05:30",
    "updated_at":"2014-01-08T07:53:41+05:30"
  }
]

그룹 수정하기

PUT /api/v2/groups/[id] 로 그룹 정보를 수정해요. 그룹에 연결된 에이전트를 모두 삭제하고 싶다면 "agent_ids":[](빈 배열)로 업데이트하면 돼요.

샘플 코드 (Curl)

curl -v -u yourapikey:*** -H "Content-Type: application/json" -X PUT -d '{
  "name":"Entertainers",
  "description":"Singers dancers and stand up comedians",
  "agent_ids":[2,15],
  "auto_ticket_assign":1
}' 'https://domain.freshdesk.com/api/v2/groups/1'

요청(Request) 본문

{
  "name":"Entertainers",
  "description":"Singers dancers and stand up comedians",
  "agent_ids":[2,15]
}

응답(Response)

{
  "id":1,
  "name":"Entertainers",
  "description":"Singers dancers and stand up comedians",
  "business_hour_id":null,
  "escalate_to":1,
  "unassigned_for":"30m",
  "agent_ids":[2,15],
  "auto_ticket_assign":1,
  "created_at":"2014-01-08T07:53:41+05:30",
  "updated_at":"2014-01-08T07:53:41+05:30"
}

그룹 삭제하기

DELETE /api/v2/groups/[id] 로 그룹을 삭제해요. 여기서 주의할 점이 두 가지예요.

그룹을 삭제해도 그룹 멤버(에이전트)는 삭제되지 않고, 다만 그룹만 해체돼요.
삭제된 그룹은 복원할 수 없어요.

curl -v -u yourapikey:*** -X DELETE 'https://domain.freshdesk.com/api/v2/groups/1'

성공하면 본문 없이 204 No Content 상태를 반환해요.

HTTP Status: 204 No Content

티켓 배정과 권한

그룹의 핵심 역할 중 하나는 바로 티켓 배정이에요. auto_ticket_assign 값으로 티켓이 그룹에 들어왔을 때 에이전트를 어떻게 자동 배정할지 정하고, escalate_to와 unassigned_for로는 티켓이 오랫동안 배정되지 않았을 때 알림을 받을 사용자와 대기 시간을 설정해요. 이렇게 티켓 할당 정책과 에스컬레이션을 그룹 단위로 관리하면, 운영팀이 어떤 티켓을 누가 처리해야 하는지 명확해져요. 단, 그룹 생성·조회·수정·삭제 등 관련 API는 모두 관리자 권한이 있어야만 호출할 수 있다는 점을 꼭 기억해 두세요.

더 세밀한 설정(스킬 기반 배정, 옴니채널, 채팅 배정 등)이 필요하다면 2021년에 출시된 새 그룹 API(/api/v2/admin/groups)를 사용하면 돼요. 화면(UI)이 새 버전으로 전환된 계정이라면 이 새 API를 활용해야 해요.

더 알아보기

공식 문서: Freshdesk API - Groups