Send ZNS

Note:

  • For APIs used for Shop, the API key is: <api_key>. The base_url information of the Shop.

  • For APIs used for Partner, the API key is: <shop_key>. The base_url information of the Partner.

SendZNS

post
Body
modestring · enumOptionalPossible values:
oa_idstring · int64Optional
phonestringOptional
sending_modestring · enumOptionalPossible values:
template_idintegerOptional
tracking_idstringOptional
Responses
200
A successful response
application/json
post
POST /SendZNS HTTP/1.1
Host: $BASE_URL.Zalo
Content-Type: application/json
Accept: */*
Content-Length: 161

{
  "mode": "unknown",
  "oa_id": "text",
  "phone": "text",
  "sending_mode": "unknown",
  "template_data": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "template_id": 1,
  "tracking_id": "text"
}
200

A successful response

{
  "campaign_id": "text",
  "created_at": "2025-07-06T21:08:42.518Z",
  "delivery_status": "unknown",
  "delivery_time": "2025-07-06T21:08:42.518Z",
  "enable_sms_on_zns_failure": true,
  "error_code": 1,
  "error_message": "text",
  "fee_main": 1,
  "fee_token": 1,
  "feedback": [
    "text"
  ],
  "id": "text",
  "is_charged": true,
  "is_development": true,
  "journey_id": "text",
  "msg_id": "text",
  "note": "text",
  "oa_id": "text",
  "phone": "text",
  "rate": 1,
  "request_time": "2025-07-06T21:08:42.518Z",
  "sent_time": "2025-07-06T21:08:42.518Z",
  "shop_id": "text",
  "sms": {
    "brandname": "text",
    "code": "text",
    "description": "text",
    "message": "text",
    "request_time": "2025-07-06T21:08:42.518Z",
    "send_time": "2025-07-06T21:08:42.518Z",
    "status": "text",
    "status_description": "text",
    "unicode": true
  },
  "status": "Z",
  "submit_time": "2025-07-06T21:08:42.518Z",
  "template_data": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "template_id": 1,
  "timeout": 1,
  "tracking_id": "text",
  "type": "unknown",
  "updated_at": "2025-07-06T21:08:42.518Z",
  "user_id": "text",
  "zl_user_id": "text"
}

Request:

curl --location '$BASE_URL.Zalo/SendZNS' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $API_KEY' \
--data '{
  "mode": "unknown",
  "oa_id": "string",
  "phone": "string",
  "sending_mode": "unknown",
  "template_data": {
    "property1": "string",
    "property2": "string"
  },
  "template_id": "<int>",
  "tracking_id": "<string>"
}'

Response:

{
  "campaign_id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "delivery_status": "unknown",
  "delivery_time": "2019-08-24T14:15:22Z",
  "error_code": 0,
  "error_message": "string",
  "fee_main": 0,
  "fee_token": 0,
  "id": "string",
  "is_charged": true,
  "is_development": true,
  "journey_id": "string",
  "msg_id": "string",
  "oa_id": "string",
  "phone": "string",
  "sent_time": "2019-08-24T14:15:22Z",
  "sending_mode": "unknown",
  "shop_id": "string",
  "status": "Z",
  "template_data": {
    "property1": "string",
    "property2": "string"
  },
  "template_id": 0,
  "timeout": 0,
  "tracking_id": "string",
  "type": "unknown",
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "string"
}

Request body structure

Parameters
Data type
Describe

mode

string

Enum: "unknown" "development" development : When you need to send a ZNS sample for testing before sending it officially, you can call the ZNS API command in development mode. Development mode only supports sending a ZNS sample to the application administrator or OA administrator.

If the mode parameter is not passed, defaults to mode = unknown

id

int64

OA ID

template_id

int

ID of the message

sending_mode

string

Send mode:

Value
Send mode name
Describe

"unknown"

Unknown

Unknown

"default"

Regular Send

ZNS messages are sent in the usual manner.

"tag3"

Send over limit

Mechanism to allow OA to send ZNS tag 3 messages exceeding the limit Note: Sending over limit mode (sending_mode = "tag3") only applies to whitelisted OAs.

phone

string

Recipient phone number

template_data

object

Properties of the message you registered with Zalo

Note: The template_data structure is specified separately for each message.

tracking_id

string

Your API call tracking number, defined by you. You can use tracking_id for reconciliation without depending on the message_id provided by eTelecom.

Return data attribute structure

Parameters
Data type
Describe

id

int64

Message ID on eTelecom system

shop_id

int64

Store ID on eTelecom system

user_id

int64

Sender ID on eTelecom system

campaign_id

int64

Campaign ID

delivery_status

string

Unkown: Unknown

Received: Received

Seen: Viewed

delivery_time

string<date-time>

Time the user's device receives the ZNS notification

error_code

int

Error code

error_message

string

Error message

fee_main

int

Main fee

fee_token

int

Token Creation Fee

is_charged

boolean

True: ZNS News is charged

False: ZNS news is free of charge

is_development

boolean

True: ZNS message in experimental development mode

False: ZNS message is not in beta development mode

journey_id

string

Journey ID

msg_id

string

ZNS message ID

type

string

template: ZNS usually

journey: ZNS journey

status

string

Status

Z: Newly created

P: Enable

N: Disable

template_data

object

Message parameters

phone

string

Recipient phone number

sent_time

string<date-time>

ZNS notification sending time

sending_mode

string

Value included:

  • "unknown": Unknown

  • "default": ZNS messages are sent in the usual way

  • "tag3": ZNS message sent by over-limit mechanism

template_id

integer

ID of the message

timeout

integer

Maximum time required by the system to process the request

tracking_id

string

Your API call tracking number, defined by you. You can use tracking_id for reconciliation without depending on the message_id provided by eTelecom.

updated_at

string<date-time>

Update date

created_at

string<date-time>

Date created

Last updated