Hubz API v1 (beta) · Hubz v0.7.0 · 2026-11-06
API reference: Hubz API v1
Tải mô tả API (OpenAPI 3.1, yaml)
https://api.hubz.vn · Mọi request cần Authorization: Bearer hbz_live_xxx.
Endpoint
GET /v1/meGET /v1/accountsGET /v1/contactsGET /v1/contacts/{id}PUT /v1/contacts/{id}/linksDELETE /v1/contacts/{id}/linksGET /v1/linksGET /v1/conversations/{id}GET /v1/conversations/{id}/messagesPOST /v1/conversations/{id}/messagesGET /v1/filesGET /v1/eventsPUT /v1/webhookDELETE /v1/webhookPOST /v1/webhook/testPOST /v1/embed-tokenPUT /v1/embed-origins
GET /v1/me
Khóa này là của công ty nào, đang hành động dưới tên ai
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
X-Hubz-User | header | string (email) | Email nhân viên để hành động dưới tên người đó. |
Trả về 200
Thành công: object
| Trường | Kiểu | |
|---|---|---|
integration | object | { id, name, scopes } |
company | object | { id, name } |
user | object | { id, name, email, role } |
accountIds | string[] |
Lỗi: xem Giới hạn và mã lỗi.
GET /v1/accounts
Các số Zalo khóa dùng được
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
X-Hubz-User | header | string (email) | Email nhân viên để hành động dưới tên người đó. |
Trả về 200
Thành công: Account[]
Lỗi: xem Giới hạn và mã lỗi.
GET /v1/contacts
Tìm khách theo số điện thoại (mọi cách viết) hoặc theo tên
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
X-Hubz-User | header | string (email) | Email nhân viên để hành động dưới tên người đó. |
phone | query | string | 0912 345 678, +84912345678, 84912345678 là một số. |
q | query | string (min 2) | |
limit | query | integer (default 20; max 100) |
Trả về 200
Thành công: Contact[]
Lỗi: xem Giới hạn và mã lỗi.
GET /v1/contacts/{id}
Một khách
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
id bắt buộc | đường dẫn | string (uuid) | |
X-Hubz-User | header | string (email) | Email nhân viên để hành động dưới tên người đó. |
Trả về 200
Thành công: Contact
Lỗi: xem Giới hạn và mã lỗi.
PUT /v1/contacts/{id}/links
Liên kết khách với một bản ghi bên phần mềm (quyền link). Gọi lại cùng giá trị không tạo trùng.
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
id bắt buộc | đường dẫn | string (uuid) |
Dữ liệu gửi lên
| Trường | Kiểu | |
|---|---|---|
externalType bắt buộc | string | |
externalId bắt buộc | string | |
externalUrl | string (uri) |
Trả về 200
Khách sau khi liên kết: Contact
Lỗi: xem Giới hạn và mã lỗi.
DELETE /v1/contacts/{id}/links
Bỏ liên kết (quyền link)
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
id bắt buộc | đường dẫn | string (uuid) | |
externalType bắt buộc | query | string | |
externalId bắt buộc | query | string |
Trả về 200
Thành công
Lỗi: xem Giới hạn và mã lỗi.
GET /v1/links
Tra ngược bản ghi bên phần mềm là khách nào trên Hubz
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
externalType bắt buộc | query | string | |
externalId bắt buộc | query | string |
Trả về 200
Thành công: Contact[]
Lỗi: xem Giới hạn và mã lỗi.
GET /v1/conversations/{id}
Một hội thoại
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
id bắt buộc | đường dẫn | string (uuid) | |
X-Hubz-User | header | string (email) | Email nhân viên để hành động dưới tên người đó. |
Trả về 200
Thành công: Conversation
Lỗi: xem Giới hạn và mã lỗi.
GET /v1/conversations/{id}/messages
Tin của hội thoại, mới nhất trước; trang tiếp theo dùng before = id tin cũ nhất đã nhận
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
id bắt buộc | đường dẫn | string (uuid) | |
X-Hubz-User | header | string (email) | Email nhân viên để hành động dưới tên người đó. |
before | query | string (uuid) |
Trả về 200
Thành công: Message[]
Lỗi: xem Giới hạn và mã lỗi.
POST /v1/conversations/{id}/messages
Gửi tin (quyền send). Có tệp kèm chữ thì tệp gửi trước, chữ sau.
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
id bắt buộc | đường dẫn | string (uuid) | |
X-Hubz-User | header | string (email) | Email nhân viên để hành động dưới tên người đó. |
Dữ liệu gửi lên
| Trường | Kiểu | |
|---|---|---|
text | string (max 4000) | |
file | object | { name, mime, base64 } |
Trả về 200
Các tin vừa xếp hàng gửi: Message[]
Lỗi: xem Giới hạn và mã lỗi.
GET /v1/files
Tải tệp của một tin (chuyển hướng 302 tới link ký sẵn 5 phút)
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
key bắt buộc | query | string |
Trả về 302
Chuyển hướng tới tệp
Lỗi: xem Giới hạn và mã lỗi.
GET /v1/events
Kéo sự kiện (quyền events)
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
after | query | integer (default 0) | Giá trị next của lần gọi trước; 0 lần đầu. |
limit | query | integer (default 100; max 500) | |
types | query | string | Lọc loại |
Trả về 200
Thành công: object
| Trường | Kiểu | |
|---|---|---|
events | Event[] | |
next | string |
Lỗi: xem Giới hạn và mã lỗi.
PUT /v1/webhook
Phần mềm tự đăng ký webhook (quyền events). Trả bí mật ký khi tạo mới, đổi địa chỉ hoặc rotateSecret.
Dữ liệu gửi lên
| Trường | Kiểu | |
|---|---|---|
url bắt buộc | string (uri) | |
events | string (message.created, message.updated, conversation.updated)[] | |
rotateSecret | boolean |
Trả về 200
Thành công: object
| Trường | Kiểu | |
|---|---|---|
url | string | |
events | string[] | |
secret | string | null |
Lỗi: xem Giới hạn và mã lỗi.
DELETE /v1/webhook
Gỡ webhook
Trả về 200
Thành công
Lỗi: xem Giới hạn và mã lỗi.
POST /v1/webhook/test
Gửi thử sự kiện ping tới webhook, trả kết quả ngay
Trả về 200
Thành công: object
| Trường | Kiểu | |
|---|---|---|
ok | boolean | |
status | integer | |
error | string | null |
Lỗi: xem Giới hạn và mã lỗi.
POST /v1/embed-token
Xin địa chỉ nhúng (một hội thoại, hoặc cả app Hubz) dưới tên nhân viên (X-Hubz-User). Khóa không có quyền send thì chỉ xem.
Tham số
| Tên | Ở | Kiểu | |
|---|---|---|---|
X-Hubz-User | header | string (email) | Email nhân viên để hành động dưới tên người đó. |
Dữ liệu gửi lên
| Trường | Kiểu | |
|---|---|---|
conversationId bắt buộc | string (uuid) |
| Trường | Kiểu | |
|---|---|---|
app bắt buộc | boolean (True) |
Trả về 200
Thành công: object
| Trường | Kiểu | |
|---|---|---|
url | string | |
token | string | |
expiresAt | string (date-time) |
Lỗi: xem Giới hạn và mã lỗi.
PUT /v1/embed-origins
Thêm trang được nhúng khung chat (origin dạng https://ten-mien)
Dữ liệu gửi lên
| Trường | Kiểu | |
|---|---|---|
origins bắt buộc | string[] |
Trả về 200
Danh sách sau khi thêm
Lỗi: xem Giới hạn và mã lỗi.
Cấu trúc dữ liệu
Error
| Trường | Kiểu | |
|---|---|---|
error | string |
Account
| Trường | Kiểu | |
|---|---|---|
id | string (uuid) | |
name | string | |
phone | string | null | |
status | string (connected, disconnected, pending_qr, banned, deleted) | |
canReply | boolean |
Link
| Trường | Kiểu | |
|---|---|---|
integrationId | string (uuid) | |
externalType | string | |
externalId | string | |
externalUrl | string | null |
Contact
| Trường | Kiểu | |
|---|---|---|
id | string (uuid) | |
type | string (person) | |
name | string | |
zaloName | string | null | |
phone | string | null | |
accountId | string | null (uuid) | |
isFriend | boolean | |
tags | string[] | |
links | Link[] | |
conversations | object[] |
Conversation
| Trường | Kiểu | |
|---|---|---|
id | string (uuid) | |
account | object | { id, name, phone } |
threadType | string (user, group) | |
contact | object | { id, name } |
assignee | object | null | { id, name } |
status | string (open, closed) | |
lastMessageAt | string | null (date-time) | |
lastMessagePreview | string | null | |
unreadCount | integer | |
canReply | boolean |
File
| Trường | Kiểu | |
|---|---|---|
name | string | |
mime | string | |
size | integer | |
key | string | Dùng với GET /v1/files để tải tệp. |
Message
| Trường | Kiểu | |
|---|---|---|
id | string (uuid) | |
conversationId | string (uuid) | |
direction | string (in, out) | |
kind | string (text, link, image, file, sticker, contact, call, other) | |
text | string | null | |
file | File | null | |
status | string (queued, sent, failed) | |
error | string | null | |
source | string (customer, web, phone, api) | |
sentBy | object | null | { id, name } |
senderName | string | null | Tên thành viên gửi tin trong nhóm chat. |
replyToId | string | null | |
recalled | boolean | |
createdAt | string (date-time) |
Event
| Trường | Kiểu | |
|---|---|---|
id | string | Tăng dần |
type | string (message.created, message.updated, conversation.updated) | |
version | integer | |
createdAt | string (date-time) | |
data | object | message.*: `{ accountId, message, conversation: { id, accountId, threadType, status, assigneeId }, contact: { id, name, phone }, firstInbound }`. `firstInbound = true` khi đây là tin đầu tiên khách gửi trong hội thoại (dùng để tạo cơ hội, phiếu mới). conversation.updated: `{ accountId, conversation: { id, accountId, threadType, status, assignee, lastMessageAt, unreadCount }, contact: { id, name } }`. |
Nội dung data theo loại sự kiện
- message.*:
{ accountId, message, conversation: { id, accountId, threadType, status, assigneeId }, contact: { id, name, phone }, firstInbound }. firstInbound = truekhi đây là tin đầu tiên khách gửi trong hội thoại (dùng để tạo cơ hội, phiếu mới).- conversation.updated:
{ accountId, conversation: { id, accountId, threadType, status, assignee, lastMessageAt, unreadCount }, contact: { id, name } }.
Hubz không phải sản phẩm của Zalo hay VNG; Hubz không dùng API chính thức của Zalo. Hubz không liên kết với Odoo S.A.; Odoo là nhãn hiệu của Odoo S.A.