Zalo — Messages

Send text message — zalo.send_text

Send a text message to a user, optionally quoting an earlier message. Free inside 48 hours of the user's last interaction, paid after that. The user must have interacted with the OA in the last 7 days.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	high	yes	no	—

Input

Field	Type	Required	Description
user_id	string	yes	Zalo user ID of the OA follower.
text	string	yes	Message text, up to 2000 characters. Max length 2000.
quote_message_id	string	no	message_id to quote and reply to.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Result of the send: message_id, user_id, sent_time and the quota used.
data.message_id	string	ID of the message Zalo accepted.
data.user_id	string	Zalo user ID of the recipient.
data.sent_time	string	When Zalo sent the message, Unix time in milliseconds, as a string.
data.quota	object	The quota that paid for the message. Missing when the message was charged instead of using a quota.
data.quota.quota_type	string	Which quota paid for the message: reply, welcome_msg, sub_quota, purchase_quota or reward_quota. The reference example for reply omits it.
data.quota.remain	string	Messages left in this quota, as a string. Only for reply, welcome_msg and sub_quota. For reply it is always "8" from 1 Jan 2026 and is no longer returned after 1 Mar 2026.
data.quota.total	string	Size of this quota, as a string. Only for reply, welcome_msg and sub_quota. No longer returned for reply after 1 Mar 2026.
data.quota.expired_date	string	Date the free package quota expires, dd/MM/yyyy. Only for sub_quota.
data.quota.owner_type	string	Who owns the purchased or reward quota: OA or App. Only for purchase_quota and reward_quota.
data.quota.owner_id	string	ID of the OA or App that owns the quota. Only for purchase_quota and reward_quota.

Send image message — zalo.send_image

Send one image or GIF, from a public url or an uploaded attachment_id (exactly one of them). Free inside 48 hours of the user's last interaction, paid after that. The user must have interacted with the OA in the last 7 days.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	high	yes	no	—

Input

Field	Type	Required	Description
user_id	string	yes	Zalo user ID of the OA follower.
media_type	string	no	One of: image, gif. Default image.
url	string	no	HTTPS URL of the image (jpg/png up to 1 MB). Pattern: ^https://.
attachment_id	string	no	attachment_id from an upload action.
width	integer	no	Required for gif. Min 1.
height	integer	no	Required for gif. Min 1.
text	string	no	Optional caption. Max length 2000.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Result of the send: message_id, user_id, sent_time and the quota used.
data.message_id	string	ID of the message Zalo accepted.
data.user_id	string	Zalo user ID of the recipient.
data.sent_time	string	When Zalo sent the message, Unix time in milliseconds, as a string.
data.quota	object	The quota that paid for the message. Missing when the message was charged instead of using a quota.
data.quota.quota_type	string	Which quota paid for the message: reply, welcome_msg, sub_quota, purchase_quota or reward_quota. The reference example for reply omits it.
data.quota.remain	string	Messages left in this quota, as a string. Only for reply, welcome_msg and sub_quota. For reply it is always "8" from 1 Jan 2026 and is no longer returned after 1 Mar 2026.
data.quota.total	string	Size of this quota, as a string. Only for reply, welcome_msg and sub_quota. No longer returned for reply after 1 Mar 2026.
data.quota.expired_date	string	Date the free package quota expires, dd/MM/yyyy. Only for sub_quota.
data.quota.owner_type	string	Who owns the purchased or reward quota: OA or App. Only for purchase_quota and reward_quota.
data.quota.owner_id	string	ID of the OA or App that owns the quota. Only for purchase_quota and reward_quota.

Send sticker — zalo.send_sticker

Send a sticker. Sticker IDs come from stickers.zaloapp.com. Free inside 48 hours of the user's last interaction, paid after that. The user must have interacted with the OA in the last 7 days.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	high	yes	no	—

Input

Field	Type	Required	Description
user_id	string	yes	Zalo user ID of the OA follower.
attachment_id	string	yes	Sticker ID.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Result of the send: message_id, user_id, sent_time and the quota used.
data.message_id	string	ID of the message Zalo accepted.
data.user_id	string	Zalo user ID of the recipient.
data.sent_time	string	When Zalo sent the message, Unix time in milliseconds, as a string.
data.quota	object	The quota that paid for the message. Missing when the message was charged instead of using a quota.
data.quota.quota_type	string	Which quota paid for the message: reply, welcome_msg, sub_quota, purchase_quota or reward_quota. The reference example for reply omits it.
data.quota.remain	string	Messages left in this quota, as a string. Only for reply, welcome_msg and sub_quota. For reply it is always "8" from 1 Jan 2026 and is no longer returned after 1 Mar 2026.
data.quota.total	string	Size of this quota, as a string. Only for reply, welcome_msg and sub_quota. No longer returned for reply after 1 Mar 2026.
data.quota.expired_date	string	Date the free package quota expires, dd/MM/yyyy. Only for sub_quota.
data.quota.owner_type	string	Who owns the purchased or reward quota: OA or App. Only for purchase_quota and reward_quota.
data.quota.owner_id	string	ID of the OA or App that owns the quota. Only for purchase_quota and reward_quota.

Send file — zalo.send_file

Send a file using the token returned by the upload_file action. Free inside 48 hours of the user's last interaction, paid after that. The user must have interacted with the OA in the last 7 days.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	high	yes	no	—

Input

Field	Type	Required	Description
user_id	string	yes	Zalo user ID of the OA follower.
token	string	yes	File token from upload_file.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Result of the send: message_id, user_id, sent_time and the quota used.
data.message_id	string	ID of the message Zalo accepted.
data.user_id	string	Zalo user ID of the recipient.
data.sent_time	string	When Zalo sent the message, Unix time in milliseconds, as a string.
data.quota	object	The quota that paid for the message. Missing when the message was charged instead of using a quota.
data.quota.quota_type	string	Which quota paid for the message: reply, welcome_msg, sub_quota, purchase_quota or reward_quota. The reference example for reply omits it.
data.quota.remain	string	Messages left in this quota, as a string. Only for reply, welcome_msg and sub_quota. For reply it is always "8" from 1 Jan 2026 and is no longer returned after 1 Mar 2026.
data.quota.total	string	Size of this quota, as a string. Only for reply, welcome_msg and sub_quota. No longer returned for reply after 1 Mar 2026.
data.quota.expired_date	string	Date the free package quota expires, dd/MM/yyyy. Only for sub_quota.
data.quota.owner_type	string	Who owns the purchased or reward quota: OA or App. Only for purchase_quota and reward_quota.
data.quota.owner_id	string	ID of the OA or App that owns the quota. Only for purchase_quota and reward_quota.

Send message with buttons — zalo.send_buttons

Send text with up to 5 buttons (open URL, quick reply, SMS, phone call). Buttons show on mobile only. The reference has no reply example for buttons; it returns the same reply as the other consultation messages. Free inside 48 hours of the user's last interaction, paid after that. The user must have interacted with the OA in the last 7 days.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	high	yes	no	—

Input

Field	Type	Required	Description
user_id	string	yes	Zalo user ID of the OA follower.
text	string	yes	Message text, up to 2000 characters. Max length 2000.
buttons	array of object	yes	Buttons, up to 5.
buttons[].title	string	yes	Max length 100.
buttons[].type	string	yes	One of: oa.open.url, oa.query.show, oa.query.hide, oa.open.sms, oa.open.phone.
buttons[].payload	object | string	yes	oa.open.url: {url}; oa.query.show / oa.query.hide: string up to 1000 chars; oa.open.sms: {content up to 160 chars, phone_code}; oa.open.phone: {phone_code}.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Result of the send: message_id, user_id, sent_time and the quota used.
data.message_id	string	ID of the message Zalo accepted.
data.user_id	string	Zalo user ID of the recipient.
data.sent_time	string	When Zalo sent the message, Unix time in milliseconds, as a string.
data.quota	object	The quota that paid for the message. Missing when the message was charged instead of using a quota.
data.quota.quota_type	string	Which quota paid for the message: reply, welcome_msg, sub_quota, purchase_quota or reward_quota. The reference example for reply omits it.
data.quota.remain	string	Messages left in this quota, as a string. Only for reply, welcome_msg and sub_quota. For reply it is always "8" from 1 Jan 2026 and is no longer returned after 1 Mar 2026.
data.quota.total	string	Size of this quota, as a string. Only for reply, welcome_msg and sub_quota. No longer returned for reply after 1 Mar 2026.
data.quota.expired_date	string	Date the free package quota expires, dd/MM/yyyy. Only for sub_quota.
data.quota.owner_type	string	Who owns the purchased or reward quota: OA or App. Only for purchase_quota and reward_quota.
data.quota.owner_id	string	ID of the OA or App that owns the quota. Only for purchase_quota and reward_quota.

Request user info — zalo.request_user_info

Send a card asking the user to share name, phone and address. The answer arrives as a user_submit_info event. Free inside 48 hours of the user's last interaction, paid after that. The user must have interacted with the OA in the last 7 days.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	high	yes	no	—

Input

Field	Type	Required	Description
user_id	string	yes	Zalo user ID of the OA follower.
title	string	yes	Max length 100.
subtitle	string	yes	Max length 500.
image_url	string	yes	Pattern: ^https://.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Result of the send: message_id, user_id, sent_time and the quota used.
data.message_id	string	ID of the message Zalo accepted.
data.user_id	string	Zalo user ID of the recipient.
data.sent_time	string	When Zalo sent the message, Unix time in milliseconds, as a string.
data.quota	object	The quota that paid for the message. Missing when the message was charged instead of using a quota.
data.quota.quota_type	string	Which quota paid for the message: reply, welcome_msg, sub_quota, purchase_quota or reward_quota. The reference example for reply omits it.
data.quota.remain	string	Messages left in this quota, as a string. Only for reply, welcome_msg and sub_quota. For reply it is always "8" from 1 Jan 2026 and is no longer returned after 1 Mar 2026.
data.quota.total	string	Size of this quota, as a string. Only for reply, welcome_msg and sub_quota. No longer returned for reply after 1 Mar 2026.
data.quota.expired_date	string	Date the free package quota expires, dd/MM/yyyy. Only for sub_quota.
data.quota.owner_type	string	Who owns the purchased or reward quota: OA or App. Only for purchase_quota and reward_quota.
data.quota.owner_id	string	ID of the OA or App that owns the quota. Only for purchase_quota and reward_quota.

Send template message by user ID — zalo.send_template_by_uid

Send an approved ZBS template to a follower by user_id. Charged per message.

Side effect	Risk	Needs approval	Idempotent	Scopes
WRITE	high	yes	no	—

Input

Field	Type	Required	Description
user_id	string	yes	Zalo user ID of the OA follower.
template_id	string	yes	Approved ZBS template ID.
template_data	object	yes	Values for the template parameters.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.