ZaloDesk OA Helpdesk API

버전 v1 · 기본 주소 https://app.zalodesk.com/api/oa/hd/v1 · Tiếng Việt

  1. 인증 · 오류 · 한도
  2. 직원 (staffKey)
  3. 배정
  4. 메시지 보내기
  5. 손님 정보 · 기록 내보내기 · 파일
  6. 통화 배분 기록
  7. 웹훅
  8. 고객 카드
  9. 자주 묻는 질문

1. 인증 · 오류 · 한도

API 키는 ZaloDesk 관리자 PC의 Zalo OA → API cho hệ thống của bạn에서 만듭니다. 키는 만들 때 한 번만 보입니다. 새 키를 만들면 이전 키는 바로 막힙니다.

Authorization: Bearer zdk.xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

2. 직원 (staffKey)

직원은 ZaloDesk Phân quyền에 있는 웹 좌석이나 직원 PC입니다. 둘 다 구글 이메일로 찾습니다(PC는 그 PC에 로그인한 구글 이메일). API는 그 좌석에 귀사의 staffKey를 붙이고 OA 역할을 정합니다. 웹 좌석이든 PC든 배정 · 기록 · 웹훅은 똑같이 됩니다.

PUT/staff/{staffKey}

{ "email": "[email protected]", "name": "Minh", "role": "member" }
필드설명
email필수. Phân quyền에 있는 웹 좌석 또는 직원 PC의 구글 이메일. 대표(소유자) 이메일이면 소유자에게 붙습니다.
role선택. member(자기 손님만) · lead(같은 상사 아래 팀원 손님 + 미배정). 관리자(admin, PC의 Quản lý)는 ZaloDesk에서만 정하고, API가 바꾸지 않습니다. 생략하면 역할을 바꾸지 않습니다.
oaId선택. 이 OA에만 역할을 줍니다. 생략하면 연결된 모든 OA.
name선택. 표시 이름.
seatId선택. 같은 이메일로 웹 좌석과 PC가 둘 다 있을 때 어느 쪽인지 고릅니다(GET /staff의 seatId).

404 seat_not_found: 그 이메일의 웹 좌석 · PC가 없음 · 409 staff_key_taken: 다른 좌석이 이미 쓰는 staffKey · 409 seat_ambiguous: 같은 이메일로 웹 좌석과 PC가 둘 다 있음, seatId를 넣으세요.

GET/staff

{ "staff": [
  { "staffKey": "minh01", "seatId": "72cc…", "kind": "web", "name": "Minh", "email": "[email protected]",
    "roles": { "2127279295181006465": "member" }, "status": "accepted" },
  { "staffKey": "hoa01", "seatId": "pc-…", "kind": "pc", "name": "Hoa", "email": "[email protected]",
    "roles": { "2127279295181006465": "admin" }, "status": "accepted" } ] }

kind: owner · web(웹 좌석) · pc(직원 PC). roles 값: admin · lead · member · null(이 OA 담당 아님). status: accepted · ready(아직 로그인 안 함). 꺼진 좌석 · 지운 PC는 목록에 없습니다.

3. 배정

POST/assign

QR 스캔을 귀사가 확인했을 때 등. 배정 기록(누가, 언제, 왜)이 남고 웹훅 conversation.assigned가 나갑니다.

{ "zaloUserId": "3051493754622285408", "staffKey": "minh01",
  "reason": "qr", "source": { "qrId": "q-17", "listingId": "p023" } }
→ 200 { "oaId": "…", "zaloUserId": "…", "staffKey": "minh01", "seatId": "…",
        "assignedAt": "2026-10-15T03:12:00.000Z", "changed": true }

staffKey: null이면 배정을 풉니다. reason은 자유 문자열(예: qr · marketer · klk), 기본값 api. source는 1KB 이하 객체로 기록에 그대로 남습니다. 409 staff_not_on_oa: 그 직원에게 이 OA 역할이 없음.

GET/conversations/{zaloUserId}/assignee?at=

그 시각의 담당 직원(계약 수수료용). at 생략 = 지금.

{ "at": "2026-10-20T07:00:00.000Z",
  "assignee": { "staffKey": "minh01", "seatId": "…", "name": "Minh" },
  "since": "2026-10-15T03:12:00.000Z" }

GET/conversations/{zaloUserId}/log

배정 기록과 열람 기록(누가 대화를 열었는지). 지울 수 없는 기록입니다.

POST/staff/{staffKey}/handover

퇴사 처리: 그 직원이 맡던 손님 전체를 다른 직원에게 한 번에 넘깁니다. 받는 직원이 이미 맡고 있던 손님은 그대로이고, 넘어온 손님이 더해집니다. 이미 막은(회수한) 좌석에서도 됩니다. 손님마다 배정 기록과 웹훅 conversation.assigned(reason: "offboarding")이 남습니다. 받는 직원에게 그 OA 역할이 없으면 member 역할이 붙습니다.

{ "to": "lan01" }
→ 200 { "from": "minh01", "to": "lan01", "conversations": 12,
        "byOa": { "2127279295181006465": 12 } }

404 staff_not_found: 없는 staffKey · 404 target_not_found: 받는 직원이 없거나 막힌 좌석 · 400 pc_not_supported: 넘기기와 막기는 웹 좌석만 됩니다. 직원 PC는 ZaloDesk Phân quyền에서 처리합니다.

POST/staff/{staffKey}/disable

퇴사 직원 좌석 막기. 막는 즉시 그 직원의 PC · 휴대폰 화면이 끊기고, 다시 로그인할 수 없습니다. to를 주면 먼저 손님 전체를 그 직원에게 넘기고(handover와 같음) 그다음 막습니다. 넘기기가 실패하면 좌석은 막히지 않습니다. 이미 막힌 좌석에 다시 불러도 됩니다(alreadyDisabled: true). 손님 대화 · 기록은 그대로 남습니다. ZaloDesk 관리자 PC의 Phân quyền → Thu hồi에서도 똑같이 할 수 있습니다.

{ "to": "lan01" }        // 생략 가능
→ 200 { "staffKey": "minh01", "disabled": true, "alreadyDisabled": false,
        "handover": { "to": "lan01", "conversations": 12, "byOa": { "2127279295181006465": 12 } } }

404 staff_not_found · 404 target_not_found · 400 disable_invalid: 소유자 계정이거나 to가 같은 직원 · 400 pc_not_supported: 직원 PC(Phân quyền에서 처리).

4. 메시지 보내기

POST/messages

{ "zaloUserId": "3051493754622285408", "text": "안녕하세요, 담당 직원 Minh입니다." }
{ "zaloUserId": "…", "imageUrl": "https://klkdevelop.com/img/p023.jpg", "caption": "🏠 The River 2PN\nhttps://klkdevelop.com/h.php?id=p023" }
→ 200 { "msgIds": ["c5f1…"] }

5. 손님 정보 · 기록 내보내기 · 파일

GET/customers/{zaloUserId}

{ "name": "Anh Minh", "avatar": "https://…", "phone": null,
  "lastMessageAt": "…", "lastCustomerAt": "…",
  "assignee": { "staffKey": "minh01", "seatId": "…", "name": "Minh" },
  "summary": ["계약 진행", "10/30 14:00 미팅", "Quận 7"] }

PUT/conversations/{zaloUserId}/summary

대화 목록에서 손님 이름 아래에 한 줄로 보이는 짧은 정보(단계, 다음 미팅, 선호 지역 등). ZaloDesk는 받은 글자를 그대로 보여 줄 뿐 해석하지 않습니다.

{ "items": ["계약 진행", "10/30 14:00 미팅", "Quận 7"] }
→ 200 { "oaId": "…", "zaloUserId": "…", "items": ["계약 진행", "10/30 14:00 미팅", "Quận 7"], "changed": true }

최대 3개, 각 30자 이하. 빈 문자열은 빠지고 []이면 지웁니다. 목록에는 계약 진행 · 10/30 14:00 미팅 · Quận 7로 보이고, 열려 있는 ZaloDesk(휴대폰 · 웹 · PC)에 바로 반영됩니다. 배정으로 일하는 직원이 있는 OA에서 보입니다. 400 summary_invalid: 3개 초과, 30자 초과, 문자열이 아닌 값.

GET/export?from=&to=&cursor=&limit=

ZaloDesk에 저장된 메시지를 기간으로 가져옵니다(서버가 멈췄던 동안 빠진 것 채우기). 매일 불러도 되고, 같은 기간을 여러 번 불러도 됩니다. limit 최대 500(기본 200). nextCursor가 null이 될 때까지 cursor로 이어 부릅니다. 순서: 손님별, 손님 안에서는 시간순.

{ "messages": [
  { "zaloUserId": "…", "at": "…", "direction": "out", "msgId": "…", "msgType": "webchat",
    "text": "Dạ còn ạ", "fileUrl": null, "sender": "staff", "staffKey": "minh01", "staffName": "Minh" },
  { "zaloUserId": "…", "at": "…", "direction": "in", "msgId": "…", "msgType": "chat.photo",
    "text": null, "fileUrl": "https://app.zalodesk.com/api/oa/hd/v1/media/9f…", "customer": { "name": "Anh Minh" } } ],
  "nextCursor": "eyJ0Ijo…" }

GET/media/{id}

웹훅과 내보내기의 fileUrl · recordingUrl. 같은 API 키로 받습니다. Zalo는 채팅 사진 · 파일을 약 14일 뒤 지우므로, 이벤트를 받을 때 내려받아 두세요.

6. 통화 배분 기록

OA로 걸려 온 전화마다 ZaloDesk가 벨 순서(계획)를 정하고, 누구에게 언제 울렸는지, 누가 거절하고 누가 받았는지 기록합니다. 순서: 담당자 → 담당자의 팀(팀별 설정) → 상위 팀 → … → 대표. 팀별 또는 사람별로 정합니다: 담당자 혼자 울리는 시간(초, 예: 20초 뒤 팀도 울림), 그리고 선택으로 연속 부재중 횟수(N번 연속 못 받으면 다음 전화는 팀도 바로 함께 울림, 담당자가 받으면 다시 0부터). 팀이 울린 뒤 상위 팀으로 넘어가는 시간도 팀별로 따로 정합니다. 담당자가 없는 새 고객은 OA의 “새 고객” 설정을 따릅니다. 설정 위치: ZaloDesk → Phân quyền → Cuộc gọi (0.9.10 이하: Chia khách tự động). 기록은 90일 보관합니다.

GET/calls/routing?oaId=&from=&to=&zaloUserId=&cursor=&limit=

최근 통화부터. limit 최대 200(기본 50). nextCursor가 null이 될 때까지 cursor로 이어 부릅니다.

GET/calls/routing/{id}?oaId=

{ "id": "1792054800000.3f9a1c2b7d4e", "oaId": "…", "zaloUserId": "…",
  "startedAt": "…", "endedAt": "…",
  "outcome": "answered",
  "answeredBy": { "staffKey": "hung01", "seatId": "…", "name": "Hùng", "kind": "web" },
  "assignee": { "staffKey": "lan01", "seatId": "…", "name": "Lan", "kind": "web" },
  "assigneeSource": "assigned",
  "steps": [
    { "index": 0, "kind": "assignee", "team": null, "waitSec": 20, "startedAt": "…", "reason": "start" },
    { "index": 1, "kind": "team", "team": { "staffKey": "minh01", "seatId": "…", "name": "Minh", "kind": "pc" },
      "waitSec": 20, "startedAt": "…", "reason": "timer" } ],
  "people": [
    { "staffKey": "lan01", "seatId": "…", "name": "Lan", "kind": "web", "step": 0, "status": "taken_by_other", "rangAt": "…", "until": "…" },
    { "staffKey": "minh01", "seatId": "…", "name": "Minh", "kind": "pc", "step": 1, "status": "declined", "rangAt": "…", "until": "…" },
    { "staffKey": "hung01", "seatId": "…", "name": "Hùng", "kind": "web", "step": 1, "status": "answered", "rangAt": "…", "until": "…" },
    { "staffKey": "tu01", "seatId": "…", "name": "Tú", "kind": "web", "step": 1, "status": "offline", "rangAt": null, "until": null, "notifiedAt": "…" } ],
  "deviations": [] }
필드값
outcomeanswered 받음 · missed 부재중 · declined 모두 거절 · ringing 울리는 중
assigneeSourceassigned 이미 배정됨 · rotation 이 전화로 차례 배정 · fixed 고정 담당 · answer 받은 사람으로 배정 · missed 부재중 후 차례 배정 · none 담당 없음
steps[].kindassignee 담당자 · team 팀(team = 팀장) · owner 대표의 팀 · new 담당자 없는 새 고객 · all 배정을 쓰지 않는 OA
steps[].misses연속 부재중 설정이 켜져 있을 때만: { "limit": N, "streak": 이 전화 직전의 연속 부재중 }. streak < limit이면 담당자 혼자 설정한 초만큼 울리고(waitSec), 아니면 팀도 바로 울립니다(waitSec 0). 그 외 null
steps[].reason그 단계가 시작된 이유: start · timer(앞 단계가 waitSec 동안 울림) · empty(앞 단계에 울릴 사람이 없음) · nobody(앞 사람들이 모두 거절 · 끊김). 시작하지 않은 단계는 null
people[].statusanswered 받음 · taken_by_other 울렸지만 다른 사람이 받음 · no_answer 울렸지만 받지 않음 · declined 거절 · left 울리는 중 연결 끊김 · no_permission 이 OA 통화 권한이 없어 건너뜀(알림 없음) · offline 앱이 꺼져 있어 건너뜀 · not_reached 차례 전에 통화가 끝남 · pending 진행 중 · not_rung 울려야 했는데 울리지 않음(ZaloDesk 오류)
people[].notifiedAt앱이 꺼져 있어 건너뛴 사람에게 전화 알림(푸시)을 보낸 시각. 보내지 않았으면 null. 알림을 누르고 통화가 울리는 동안 ZaloDesk를 열면 그 사람도 울리고 받을 수 있습니다
deviations계획과 다르게 울린 점. 비어 있지 않으면 ZaloDesk가 자동으로 오류를 받아 고칩니다.

7. 웹훅

웹훅 주소(https)는 ZaloDesk 관리자 PC의 같은 화면에서 넣습니다. 서명 키(whsec_…)는 고객 카드 키, API 키와 별개입니다.

POST {귀사 주소}
Content-Type: application/json
X-ZaloDesk-Event: message.sent
X-ZaloDesk-Delivery: evt_3caa071d9727f28494f61dfa
X-ZaloDesk-Signature: t=1791989815,v1=5d1c…

{ "id": "evt_3caa071d9727f28494f61dfa", "type": "message.sent", "at": "2026-10-15T03:12:05.000Z",
  "oaId": "2127279295181006465", "zaloUserId": "3051493754622285408", "data": { … } }

서명 확인 (PHP)

$raw = file_get_contents('php://input');
preg_match('/t=(\d+),v1=([a-f0-9]+)/', $_SERVER['HTTP_X_ZALODESK_SIGNATURE'] ?? '', $m);
$ok = $m && abs(time() - (int)$m[1]) < 300
  && hash_equals(hash_hmac('sha256', $m[1] . '.' . $raw, ZD_WEBHOOK_SECRET), $m[2]);
if (!$ok) { http_response_code(401); exit; }
$event = json_decode($raw, true);
// $event['id'] 중복 확인 → 저장 → 200

이벤트

typedata
message.receivedmsgId(Zalo 글 번호) · msgType · text · fileUrl · title · customer: {name, avatar}
message.sentmsgId · msgType · text · fileUrl · sender · staffKey · staffName
sender: staff(직원이 ZaloDesk에서 보냄) · auto(자동 응답 · 인사말) · api(귀사 서버가 /messages로 보냄) · ai(AI 답장, 예약) · external(OA Manager나 귀사 앱 등 ZaloDesk 밖에서 보냄)
conversation.assignedfrom · to · by(각각 {staffKey, seatId} 또는 null, by는 "api"일 수 있음) · reason · source
conversation.viewedstaffKey · seatId (같은 직원 · 같은 대화는 5분에 한 번)
call.endedcallId · direction(in/out) · startedAt · talkSeconds · missed · video (Zalo가 알려 주는 통화 종료)
call.recordedcallId · direction · startedAt · endedAt · durationSeconds · staffKey(받은 · 건 직원) · staffName · recordingUrl · transcript(pending/none)
call.transcriptcallId · lines: [{at(ms), s("c" 손님 | "s" 직원), x(문장)}]
call.routedOA로 걸려 온 통화가 끝나면: GET /calls/routing/{id}와 같은 내용(누구에게 언제 울렸고 누가 받았는지)
customer.followed · customer.unfollowed(없음)
customer.updatedname · phone (손님이 정보 양식을 보냈을 때)
pingmessage (테스트)

같은 통화에서 call.ended와 call.recorded는 callId가 다를 수 있습니다(Zalo 번호 · 교환기 번호). zaloUserId와 시각으로 맞추세요.

8. 고객 카드

카드 페이지를 만들 때:

token 확인 (PHP, 그대로 붙여 넣기)

// 카드 키: ZaloDesk PC → Cài đặt → Zalo OA → Thẻ khách hàng
function zalodesk_card($token, $key, $origin) {
  $parts = explode('.', (string) $token);
  if (count($parts) !== 3) return null;
  [$h, $p, $s] = $parts;
  $sig = rtrim(strtr(base64_encode(hash_hmac('sha256', "$h.$p", $key, true)), '+/', '-_'), '=');
  if (!hash_equals($sig, $s)) return null;
  $c = json_decode(base64_decode(strtr($p, '-_', '+/')), true);
  if (!is_array($c) || ($c['aud'] ?? '') !== $origin || ($c['exp'] ?? 0) < time()) return null;
  return $c; // oaId, zaloUserId, staff { key, email, name, role }, assigneeId
}

// api.php: 카드에서 오는 모든 요청
$card = zalodesk_card($_SERVER['HTTP_X_ZALODESK_TOKEN'] ?? '', ZALODESK_CARD_KEY, 'https://카드-페이지-도메인');
if (!$card) { http_response_code(401); exit; }
// 손님은 요청 값이 아니라 $card['zaloUserId'], 직원은 $card['staff']['key']로 정합니다.

카드 페이지 (JS, 그대로 붙여 넣기)

let token = new URLSearchParams(location.search).get('token');
let tokenWaiters = [];

addEventListener('message', (e) => {
  if (e.source !== window.parent) return;
  if (e.data?.type === 'zalodesk.token') { token = e.data.token; tokenWaiters.forEach((done) => done()); tokenWaiters = []; }
  if (e.data?.type === 'zalodesk.event') { /* message.received · message.sent · assignee.changed: 화면을 다시 읽기 */ }
});

const newToken = () => new Promise((done) => {
  tokenWaiters.push(done);
  window.parent.postMessage({ type: 'zalodesk.token.request' }, '*');
  setTimeout(done, 3000);
});

// 귀사 api.php 호출: token을 붙이고, 만료(401)면 새 token으로 한 번 더
async function api(body) {
  const send = () => fetch('/api.php', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-ZaloDesk-Token': token }, body: JSON.stringify(body) });
  let res = await send();
  if (res.status === 401) { await newToken(); res = await send(); }
  return res;
}

// 매물 사진 + 글을 답장 칸에 넣기 (보내기는 직원이 누름)
async function insertListing(photoUrl, text) {
  const file = await (await fetch(photoUrl)).blob();
  window.parent.postMessage({ type: 'zalodesk.compose', text, file }, '*');
}

9. 자주 묻는 질문

ZaloDesk가 OA 이름으로 보낸 글도 귀사 Zalo 앱 웹훅(oa_send_text 등)으로 옵니까?

네. 같은 OA에 연결된 Zalo 앱은 OA가 보낸 글을 어느 도구에서 보냈든 받습니다(귀사 앱이 보낸 글도 ZaloDesk 쪽에 그렇게 들어옵니다). 그 글의 msg_id가 웹훅 message.sent의 msgId와 같으니, 글 번호로 맞춰 보낸 직원(staffKey)을 붙이면 됩니다.

시험은 어떻게 합니까?

실제 OA로 합니다. 키를 만들고 웹훅 주소를 넣은 뒤 Gửi thử로 서명 확인을 먼저 맞추고, 직원 한 명을 PUT /staff로 붙여 손님 대화를 /assign해 보세요.