Hubz API v1 (beta) · Hubz v0.7.0 · 2026-11-06
API reference: Hubz API v1
Download the API description (OpenAPI 3.1, yaml)
https://api.hubz.vn · Every request needs Authorization: Bearer hbz_live_xxx.
Endpoints
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
Which company the key belongs to and who it acts as
Parameters
| Name | In | Type | |
|---|---|---|---|
X-Hubz-User | header | string (email) | Email of the staff member to act as. |
Returns 200
Success: object
| Field | Type | |
|---|---|---|
integration | object | { id, name, scopes } |
company | object | { id, name } |
user | object | { id, name, email, role } |
accountIds | string[] |
Errors: see Rate limits and errors.
GET /v1/accounts
The Zalo accounts the key can use
Parameters
| Name | In | Type | |
|---|---|---|---|
X-Hubz-User | header | string (email) | Email of the staff member to act as. |
Returns 200
Success: Account[]
Errors: see Rate limits and errors.
GET /v1/contacts
Find contacts by phone number (any format) or by name
Parameters
| Name | In | Type | |
|---|---|---|---|
X-Hubz-User | header | string (email) | Email of the staff member to act as. |
phone | query | string | 0912 345 678, +84912345678 and 84912345678 are the same number. |
q | query | string (min 2) | |
limit | query | integer (default 20; max 100) |
Returns 200
Success: Contact[]
Errors: see Rate limits and errors.
GET /v1/contacts/{id}
One contact
Parameters
| Name | In | Type | |
|---|---|---|---|
id required | path | string (uuid) | |
X-Hubz-User | header | string (email) | Email of the staff member to act as. |
Returns 200
Success: Contact
Errors: see Rate limits and errors.
PUT /v1/contacts/{id}/links
Link a contact to a record in your software (link scope). Calling again with the same values creates no duplicate.
Parameters
| Name | In | Type | |
|---|---|---|---|
id required | path | string (uuid) |
Request body
| Field | Type | |
|---|---|---|
externalType required | string | |
externalId required | string | |
externalUrl | string (uri) |
Returns 200
The contact once linked: Contact
Errors: see Rate limits and errors.
DELETE /v1/contacts/{id}/links
Remove a link (link scope)
Parameters
| Name | In | Type | |
|---|---|---|---|
id required | path | string (uuid) | |
externalType required | query | string | |
externalId required | query | string |
Returns 200
Success
Errors: see Rate limits and errors.
GET /v1/links
Find which Hubz contact a record of your software is
Parameters
| Name | In | Type | |
|---|---|---|---|
externalType required | query | string | |
externalId required | query | string |
Returns 200
Success: Contact[]
Errors: see Rate limits and errors.
GET /v1/conversations/{id}
One conversation
Parameters
| Name | In | Type | |
|---|---|---|---|
id required | path | string (uuid) | |
X-Hubz-User | header | string (email) | Email of the staff member to act as. |
Returns 200
Success: Conversation
Errors: see Rate limits and errors.
GET /v1/conversations/{id}/messages
Messages of a conversation, newest first; for the next page, before = id of the oldest message received
Parameters
| Name | In | Type | |
|---|---|---|---|
id required | path | string (uuid) | |
X-Hubz-User | header | string (email) | Email of the staff member to act as. |
before | query | string (uuid) |
Returns 200
Success: Message[]
Errors: see Rate limits and errors.
POST /v1/conversations/{id}/messages
Send a message (send scope). With a file and text, the file is sent first, then the text.
Parameters
| Name | In | Type | |
|---|---|---|---|
id required | path | string (uuid) | |
X-Hubz-User | header | string (email) | Email of the staff member to act as. |
Request body
| Field | Type | |
|---|---|---|
text | string (max 4000) | |
file | object | { name, mime, base64 } |
Returns 200
The messages queued for sending: Message[]
Errors: see Rate limits and errors.
GET /v1/files
Download the file of a message (302 redirect to a link signed for 5 minutes)
Parameters
| Name | In | Type | |
|---|---|---|---|
key required | query | string |
Returns 302
Redirect to the file
Errors: see Rate limits and errors.
GET /v1/events
Pull events (events scope)
Parameters
| Name | In | Type | |
|---|---|---|---|
after | query | integer (default 0) | The next value of the previous call; 0 the first time. |
limit | query | integer (default 100; max 500) | |
types | query | string | Lọc loại |
Returns 200
Success: object
| Field | Type | |
|---|---|---|
events | Event[] | |
next | string |
Errors: see Rate limits and errors.
PUT /v1/webhook
Register your webhook (events scope). Returns the signing secret when created, when the address changes or with rotateSecret.
Request body
| Field | Type | |
|---|---|---|
url required | string (uri) | |
events | string (message.created, message.updated, conversation.updated)[] | |
rotateSecret | boolean |
Returns 200
Success: object
| Field | Type | |
|---|---|---|
url | string | |
events | string[] | |
secret | string | null |
Errors: see Rate limits and errors.
DELETE /v1/webhook
Remove the webhook
Returns 200
Success
Errors: see Rate limits and errors.
POST /v1/webhook/test
Send a ping event to the webhook and return the result at once
Returns 200
Success: object
| Field | Type | |
|---|---|---|
ok | boolean | |
status | integer | |
error | string | null |
Errors: see Rate limits and errors.
POST /v1/embed-token
Get an embed address (one conversation, or the whole Hubz app) as a staff member (X-Hubz-User). Without the send scope it is read only.
Parameters
| Name | In | Type | |
|---|---|---|---|
X-Hubz-User | header | string (email) | Email of the staff member to act as. |
Request body
| Field | Type | |
|---|---|---|
conversationId required | string (uuid) |
| Field | Type | |
|---|---|---|
app required | boolean (True) |
Returns 200
Success: object
| Field | Type | |
|---|---|---|
url | string | |
token | string | |
expiresAt | string (date-time) |
Errors: see Rate limits and errors.
PUT /v1/embed-origins
Allow pages to embed the chat (origins such as https://your-domain)
Request body
| Field | Type | |
|---|---|---|
origins required | string[] |
Returns 200
The list once updated
Errors: see Rate limits and errors.
Schemas
Error
| Field | Type | |
|---|---|---|
error | string |
Account
| Field | Type | |
|---|---|---|
id | string (uuid) | |
name | string | |
phone | string | null | |
status | string (connected, disconnected, pending_qr, banned, deleted) | |
canReply | boolean |
Link
| Field | Type | |
|---|---|---|
integrationId | string (uuid) | |
externalType | string | |
externalId | string | |
externalUrl | string | null |
Contact
| Field | Type | |
|---|---|---|
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
| Field | Type | |
|---|---|---|
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
| Field | Type | |
|---|---|---|
name | string | |
mime | string | |
size | integer | |
key | string | Use with GET /v1/files to download the file. |
Message
| Field | Type | |
|---|---|---|
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 | Name of the group member who sent the message. |
replyToId | string | null | |
recalled | boolean | |
createdAt | string (date-time) |
Event
| Field | Type | |
|---|---|---|
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 } }`. |
Content of data by event type
- message.*:
{ accountId, message, conversation: { id, accountId, threadType, status, assigneeId }, contact: { id, name, phone }, firstInbound }. firstInbound = truefor the first message the customer sends in the conversation (use it to open a new lead or ticket).- conversation.updated:
{ accountId, conversation: { id, accountId, threadType, status, assignee, lastMessageAt, unreadCount }, contact: { id, name } }.
Hubz is not affiliated with Zalo or VNG; Hubz does not use Zalo’s official API. Hubz is not affiliated with Odoo S.A.; Odoo is a trademark of Odoo S.A.