zendesk-api

Zendesk API

Zendesk API는 여러분이 만든 **앱(app)**이나 **통합(integration)**이 Zendesk의 핵심 기능에 연결해서 티켓(ticket), 사용자(user), 조직(organization) 데이터를 읽고 쓰고, 헬프 센터 지식을 관리하고, 라이브 채팅이나 음성 통화 같은 고객 지원 흐름을 자동화할 수 있게 해 주는 공식 개발 인터페이스예요. 숙련된 개발자든 Zendesk를 이제 막 시작한 분이든, 대부분의 API는 제품 기능 단위(capability)로 정리되어 있어서 원하는 기능의 문서를 찾아 바로 시작할 수 있어요.

Zendesk API는 티케팅(Ticketing), 헬프 센터, 라이브 채팅, 음성, 세일즈 CRM 같은 각 기능 영역별로 나뉘어 있어요. 그리고 옴니채널 라우팅이나 커스텀 데이터처럼 여러 기능에 걸쳐 쓰이는 것들도 따로 제공돼요. 각 API 문서에는 누가 요청을 인증(authenticate)할 수 있는지, 엔드포인트의 상세한 설명, 요청 예시, 그리고 Zendesk의 가능성을 최대한 활용하는 데 필요한 필수 정보가 담겨 있어요.

# API 호출 공통 베이스 URL (예: 티켓 목록 조회)
curl -s https://your_subdomain.zendesk.com/api/v2/tickets.json \
  -u "[email protected]/token:your_api_token"

빠르게 시작하려면 Zendesk Public Workspace on Postman을 이용할 수 있어요. 이 컬렉션에는 Sell과 Sunshine Conversations API를 제외한 모든 Zendesk API가 포함되어 있으니, 예시 요청을 그대로 실행해 보며 동작을 파악하기 좋아요.

출처: 문서

본문

핵심 티케팅 API (Ticket·User·Organization)

티케팅(ticketing)은 Zendesk의 가장 중심이 되는 기능 영역이에요. Support API를 통해 티켓(ticket), 사용자(user), 조직(organization)을 다루고, 티켓 워크플로를 관리할 수 있어요. 세 가지 핵심 리소스를 살펴볼게요.

Ticket(티켓) — 고객의 문의를 나타내는 객체예요. subject, description, status, priority, requester_id, assignee_id 같은 필드를 가지며, 생성·조회·수정·삭제가 가능해요.
User(사용자) — 고객과 상담사(agent), 관리자(admin)를 모두 포함하는 계정 사용자예요. Zendesk API의 모든 요청은 기본적으로 사용자 인증을 거쳐요.
Organization(조직) — 사용자들을 묶는 단위예요. 조직 단위로 티켓을 분류하거나, 계약·서비스 수준(SLA) 설정을 적용하는 데 써요.

Ticketing 영역에는 Support API 외에도 JIRA Integration API가 있어서 Zendesk 티켓과 JIRA 이슈를 연결할 수 있어요.

인증 (Authentication)

Zendesk API는 대부분 Basic Auth(기본 인증) 또는 OAuth 2.0을 지원해요. 개인적인 사용이나 테스트에는 API 토큰을 쓴 Basic Auth가 간단해요. 토큰은 Zendesk 관리 센터(Admin Center)의 API 섹션에서 발급할 수 있고, 토큰은 비밀번호와 같으므로 절대 공개하거나 버전 관리 시스템에 올리면 안 돼요.

# Basic Auth + API 토큰으로 쓴 요청 예시
curl -u "[email protected]/token:your_api_token" \
  "https://your_subdomain.zendesk.com/api/v2/tickets/1.json"

외부 앱이나 서드파티 통합처럼 사용자 대신 API를 호출해야 하는 경우에는 OAuth 2.0을 쓰는 게 좋아요. OAuth 액세스 토큰은 Authorization: Bearer <token> 헤더로 전달해요. OAuth를 쓰면 API 토큰을 공유하지 않아도 되고, 사용자가 직접 권한(scope)을 승인하기 때문에 보안에 더 좋아요.

# OAuth 액세스 토큰으로 쓴 요청 예시
curl "https://your_subdomain.zendesk.com/api/v2/tickets.json" \
  -H "Authorization: Bearer your_oauth_access_token"

티켓 생성 예시

새 티켓을 생성하는 요청은 다음과 같아요. 요청 본문이 JSON이고, ticket 키 아래에 필드를 담아요.

curl -s -X POST "https://your_subdomain.zendesk.com/api/v2/tickets.json" \
  -u "[email protected]/token:your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": {
      "subject": "My printer is on fire!",
      "comment": {
        "body": "The smoke is very colorful."
      },
      "priority": "urgent"
    }
  }'

성공하면 생성된 티켓 객체가 JSON으로 돌아와요. status_code 201이 반환되며 티켓의 id를 받아 후속 작업(댓글 추가, 상태 변경 등)에 사용할 수 있어요.

웹훅 (Webhooks)

Zendesk에서 이벤트가 발생했을 때 여러분의 서버로 알림을 보내려면 **웹훅(webhook)**을 써요. 예를 들어 티켓이 생성되거나 상태가 바뀔 때 트리거(trigger)나 자동화(automation)와 연결해 외부 시스템에 POST 요청을 보낼 수 있어요. 이렇게 하면 Zendesk 쪽에서 주기적으로 폴링(polling)하지 않아도 외부 앱이 실시간으로 변화를 감지할 수 있어요.

Webhooks는 Zendesk Extensions > Webhooks에서 구성할 수 있고, 요청을 보낼 대상 URL과 인증 정보, 이벤트 필터를 설정해요. 또한 **Zendesk Integration Services (ZIS)**를 통해 통합 서비스를 만들면 ZIS Inbound Webhooks API 등으로 더 체계적인 웹훅 기반 통합을 구축할 수도 있어요.

그 밖의 주요 기능 영역

Help Center API — 헬프 센터, 지식 베이스, 커뮤니티를 관리해요.
AI Agents API — 대화를 자동화하고 지능적인 워크플로를 관리해요.
Conversations API — 모든 채널의 메시지를 하나의 대화로 통합해요.
Talk API — 음성 통화(콜 센터) 기능을 다뤄요.
Chat API — 라이브 채팅과 실시간 메시징을 제공해요.
Custom Objects API — 고객 데이터를 어디에 있든 연결하고 이해해요.
Omnichannel APIs — 여러 Zendesk 채널에 걸쳐 쓰이는 기능을 제공해요.
Status API — Zendesk 가용성에 영향을 줄 수 있는 진행 중인 인시던트와 예정된 유지보수 목록을 가져와요.
Sales CRM (Sell API 등) — 영업 자동화, 동기화, 파이어호스, 검색 API를 제공해요.
Apps API & SDK — Zendesk Support·Sell·Chat용 **앱(Apps)**을 만드는 API와, 웹 위젯·Android/iOS SDK·Unity SDK를 제어하는 API를 제공해요.

사용 예시 요약

티켓 목록 조회: GET /api/v2/tickets.json — Basic Auth(토큰) 또는 OAuth.
티켓 생성: POST /api/v2/tickets.json — JSON 본문의 ticket 객체.
티켓 상세 조회: GET /api/v2/tickets/{id}.json
사용자 조회: GET /api/v2/users/{id}.json
조직 조회: GET /api/v2/organizations/{id}.json
실시간 이벤트 수신: Webhooks(Extension) 또는 ZIS Inbound Webhooks API.

Zendesk는 Developer Forum과 Slack 커뮤니티에서 개발자 지원을 제공하며, API 변경 소식은 Changelog에서 확인할 수 있어요. 잘 검증된 공식 라이브러리와 Postman 컬렉션을 활용하면 인증과 요청 형식을 빠르게 잡고 시작할 수 있어요.

더 알아보기 (Learn more)

공식 문서