ZaloDesk OA Helpdesk API
버전 v1 · 기본 주소 https://app.zalodesk.com/api/oa/hd/v1 · Tiếng Việt
1. 인증 · 오류 · 한도
API 키는 ZaloDesk 관리자 PC의 Zalo OA → API cho hệ thống của bạn에서 만듭니다. 키는 만들 때 한 번만 보입니다. 새 키를 만들면 이전 키는 바로 막힙니다.
Authorization: Bearer zdk.xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
- 손님은
zaloUserId= OA 기준 사용자 번호(Zalo 웹훅의sender.id/recipient.id)로 부릅니다. 앱 기준 번호(user_id_by_app)가 아닙니다. - 직원은 귀사의 직원 아이디
staffKey(영문 소문자 · 숫자 ·-·_, 64자 이하)로 부릅니다. - OA가 하나만 연결되어 있으면
oaId는 생략해도 됩니다. - 시간은 ISO 8601(
2026-10-20T14:00:00+07:00) 또는 epoch(초 · 밀리초)를 받습니다. 응답은 UTC ISO입니다. - 오류:
{"error":"code","message":"…"}+ HTTP 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 502. - 한도: 워크스페이스당 분당 300회. 넘으면 429.
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…"] }
- OA 상담 메시지로 나갑니다. Zalo 규칙 그대로: 손님의 마지막 메시지 후 48시간 안은 무료, 그 뒤는 OA 월 한도, 7일 뒤는 Zalo가 거부합니다.
- 사진:
imageUrl은 https, JPG · PNG 1MB 이하 · GIF 5MB 이하(Zalo OA 제한). - 이 메시지는 웹훅
message.sent에서sender: "api"로 옵니다.
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": [] }
| 필드 | 값 |
|---|---|
outcome | answered 받음 · missed 부재중 · declined 모두 거절 · ringing 울리는 중 |
assigneeSource | assigned 이미 배정됨 · rotation 이 전화로 차례 배정 · fixed 고정 담당 · answer 받은 사람으로 배정 · missed 부재중 후 차례 배정 · none 담당 없음 |
steps[].kind | assignee 담당자 · 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[].status | answered 받음 · 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": { … } }
- 2xx를 10초 안에 돌려주면 성공. 아니면 30초 · 1분 · 2분 … 최대 1시간 간격으로 24시간 동안 다시 보냅니다.
- 같은 이벤트는 다시 보내도
id가 같습니다. 이미 받은id는 무시하세요. - 순서는 보장하지 않습니다.
at으로 정렬하세요. - 보낸 기록(최근 30건, 상태 코드)은 관리자 화면 Lần gửi gần đây에 보입니다. Gửi thử 또는
POST /webhook/test로ping을 보내 볼 수 있습니다.
서명 확인 (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
이벤트
| type | data |
|---|---|
message.received | msgId(Zalo 글 번호) · msgType · text · fileUrl · title · customer: {name, avatar} |
message.sent | msgId · msgType · text · fileUrl · sender · staffKey · staffNamesender: staff(직원이 ZaloDesk에서 보냄) · auto(자동 응답 · 인사말) · api(귀사 서버가 /messages로 보냄) · ai(AI 답장, 예약) · external(OA Manager나 귀사 앱 등 ZaloDesk 밖에서 보냄) |
conversation.assigned | from · to · by(각각 {staffKey, seatId} 또는 null, by는 "api"일 수 있음) · reason · source |
conversation.viewed | staffKey · seatId (같은 직원 · 같은 대화는 5분에 한 번) |
call.ended | callId · direction(in/out) · startedAt · talkSeconds · missed · video (Zalo가 알려 주는 통화 종료) |
call.recorded | callId · direction · startedAt · endedAt · durationSeconds · staffKey(받은 · 건 직원) · staffName · recordingUrl · transcript(pending/none) |
call.transcript | callId · lines: [{at(ms), s("c" 손님 | "s" 직원), x(문장)}] |
call.routed | OA로 걸려 온 통화가 끝나면: GET /calls/routing/{id}와 같은 내용(누구에게 언제 울렸고 누가 받았는지) |
customer.followed · customer.unfollowed | (없음) |
customer.updated | name · phone (손님이 정보 양식을 보냈을 때) |
ping | message (테스트) |
같은 통화에서 call.ended와 call.recorded는 callId가 다를 수 있습니다(Zalo 번호 · 교환기 번호). zaloUserId와 시각으로 맞추세요.
8. 고객 카드
- ZaloDesk는 카드 페이지를
?oaId=&zaloUserId=&token=로 엽니다.zaloUserId는 OA 기준 번호입니다. - token: HS256 JWT(카드 키로 서명), 10분.
{ iss:"zalodesk", aud:<페이지 origin>, oaId, zaloUserId, staff:{ id, key, email, name, role }, assigneeId, iat, exp }.staff.key= 그 직원의 staffKey. - 다른 대화로 옮기면 페이지를 새 손님으로 다시 엽니다.
- 새 token: ZaloDesk가 8분마다
{type:"zalodesk.token", token, expiresAt}를 보냅니다. 페이지가{type:"zalodesk.token.request"}를 보내면 바로 보냅니다. - 이벤트:
{type:"zalodesk.event", event:"message.received" | "message.sent" | "assignee.changed", oaId, zaloUserId, at}. - 답장 칸에 넣기: 카드가
window.parent.postMessage({type:"zalodesk.compose", text, file}, "*")를 보내면text는 답장 칸에 덧붙고file(이미지 File/Blob 1개, 20MB 이하)은 첨부됩니다. 보내기는 직원이 누르므로 보낸 사람은 그 직원입니다. 휴대폰에서는 카드가 닫히고 답장 칸이 보입니다. 매물 사진은 카드 페이지가 자기 서버에서fetch로 받아 Blob으로 넘기면 됩니다. - ZaloDesk는 카드에 보이는 정보를 저장하지 않습니다.
카드 페이지를 만들 때:
- 로그인: 카드는 ZaloDesk 안의 iframe이라 귀사 사이트의 로그인 쿠키가 오지 않습니다. 귀사 서버로 가는 요청마다 token을 함께 보내고, 서버에서 카드 키로 HS256 서명,
aud(페이지 origin),exp를 확인하세요. 보고 있는 직원은staff.key입니다. - iframe 허용:
X-Frame-Options나frame-ancestors로 막지 마세요. PC 앱은 카드를 로컬 파일 화면 안에서 열기 때문에app.zalodesk.com만 허용하면 PC에서 보이지 않습니다. 보호는 token이 합니다. - postMessage: 받을 때는 origin 대신
event.source === window.parent로 확인하고, 보낼 때는"*"로 보내세요(PC 앱 화면은 로컬 파일이라 origin이 웹과 다릅니다). 카드가 보내는 메시지에는 비밀이 없습니다. - 화면: 휴대폰에서는 채팅 위 전체 화면, 넓은 화면과 PC에서는 채팅 오른쪽 칸(직원이 끌어서 넓힐 수 있음)입니다. 폭에 맞춰 늘어나는 반응형 페이지로 만드세요(320px부터).
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해 보세요.