Zalo — ZBS templates

Send ZBS template message — zalo.send_template

Send an approved ZBS template to a phone number. Costs money per message (from 200 VND).

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

Input

Field	Type	Required	Description
phone	string	yes	Recipient phone: 84987654321, +84987654321 or 0987654321. Pattern: ^\+?[0-9]{9,15}$.
template_id	string	yes	ZBS template ID.
template_data	object	yes	Template parameters; names come from get_template listParams.
tracking_id	string	yes	Your reference for reconciliation; no special characters. Max length 48.
sending_mode	any	no	1 normal (default); 3 over-quota, whitelisted OAs and tag 3 only. One of: 1, 3.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

Send ZBS template message by hashed phone — zalo.send_template_hashphone

Send an approved ZBS template to a SHA-256 hashed phone number. Costs money per message.

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

Input

Field	Type	Required	Description
hash_phone	string	yes	SHA-256 of the phone number.
template_id	string	yes	ZBS template ID.
template_data	object	yes	Template parameters; names come from get_template listParams.
tracking_id	string	yes	Your reference for reconciliation; no special characters. Max length 48.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

Send ZBS template message (development mode) — zalo.send_template_dev

Test-send a ZBS template in development mode. Only admins of the App or OA can receive it.

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

Input

Field	Type	Required	Description
phone	string	yes	Recipient phone: 84987654321, +84987654321 or 0987654321. Pattern: ^\+?[0-9]{9,15}$.
template_id	string	yes	ZBS template ID.
template_data	object	yes	Template parameters; names come from get_template listParams.
tracking_id	string	yes	Your reference for reconciliation; no special characters. Max length 48.
mode	any	no	Set by FLAE Always development.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

Get ZBS message status — zalo.get_message_status

Get the delivery status of a ZBS message: -1 not found, 0 pushed, 1 delivered.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	—

Input

Field	Type	Required	Description
message_id	string	yes	msg_id returned by the send.
phone	string	no

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

Get ZBS quota — zalo.get_quota

Get the daily and remaining ZBS message quota of the OA.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	—

Input

No input.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

Get ZBS quality — zalo.get_quality

Get the OA's ZBS sending quality (last 48 hours and 7 days).

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	—

Input

No input.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

List ZBS templates — zalo.list_templates

List ZBS templates, newest first.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	—

Input

Field	Type	Required	Description
offset	integer	yes	Min 0.
limit	integer	yes	Min 1. Max 100.
status	integer	no	1 ENABLE, 2 PENDING_REVIEW, 3 REJECT, 4 DISABLE; omit for all. Min 1. Max 4.
filterPreset	integer	no	0 all OA templates, 1 only those created by this App. One of: 0, 1.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

Get ZBS template — zalo.get_template

Get a ZBS template: status, listParams, listButtons, price_sdt (phone) and price_uid.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	—

Input

Field	Type	Required	Description
template_id	string	yes	ZBS template ID.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

Get ZBS template sample data — zalo.get_template_sample_data

Get sample values for the parameters of a ZBS template.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	—

Input

Field	Type	Required	Description
template_id	string	yes	ZBS template ID.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

Create ZBS template — zalo.create_template

Create a ZBS template (100 per day). It starts as PENDING_REVIEW; Zalo reports the result by webhook.

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

Input

Field	Type	Required	Description
template_name	string	yes	Max length 60.
template_type	integer	yes	1 custom, 2 OTP, 3 payment request, 4 voucher, 5 service rating. One of: 1, 2, 3, 4, 5.
tag	string	yes	1 transaction, 2 customer care, 3 promotion. One of: 1, 2, 3.
layout	object	yes	{header, body, footer}, each with a components list.
params	array of object	yes	[{name, type, sample_value}].
note	string	yes	Max length 400.
tracking_id	string	yes	Max length 48.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

Edit ZBS template — zalo.edit_template

Edit a ZBS template. Only templates in REJECT status can be edited (100 per day).

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

Input

Field	Type	Required	Description
template_id	string	yes	ZBS template ID.
template_name	string	yes	Max length 60.
template_type	integer	yes	1 custom, 2 OTP, 3 payment request, 4 voucher, 5 service rating. One of: 1, 2, 3, 4, 5.
tag	string	yes	1 transaction, 2 customer care, 3 promotion. One of: 1, 2, 3.
layout	object	yes	{header, body, footer}, each with a components list.
params	array of object	yes	[{name, type, sample_value}].
note	string	yes	Max length 400.
tracking_id	string	yes	Max length 48.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

Upload ZBS template image — zalo.upload_template_image

Upload a JPG or PNG (max 500 KB) for a ZBS template. Returns media_id.

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

Input

Field	Type	Required	Description
file_url	string	yes	HTTPS URL of the file to upload (max 500000 bytes). Pattern: ^https://.
file_name	string	no	File name to send to Zalo.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

List ZBS ratings — zalo.list_ratings

List customer ratings for a service-rating ZBS template created by this App.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	—

Input

Field	Type	Required	Description
template_id	string	yes	ZBS template ID.
from_time	integer	yes	Start, ms timestamp.
to_time	integer	yes	End, ms timestamp.
offset	integer	yes	Min 0.
limit	integer	yes	Min 1. Max 100.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.

List ZBS quick responses — zalo.list_quick_responses

List quick-response button replies customers sent to a ZBS template.

Side effect	Risk	Needs approval	Idempotent	Scopes
NONE	low	no	yes	—

Input

Field	Type	Required	Description
template_id	string	yes	ZBS template ID.
from_time	integer	yes	Start, ms timestamp.
to_time	integer	yes	End, ms timestamp.
offset	integer	yes	Min 0.
limit	integer	yes	Min 1. Max 100.

Extra fields: ignored.

Output

Field	Type	Description
data	object	Zalo response data.