Send ZNS Notifications

Initiate messaging service to Zalo numbers via API

• URL：https://api.nxcloud.com/v1/zalo/mt
• Method：POST
• Content-Type：application/json
• Authentication required：Yes

Authentication Mechanism

Please refer to the authentication rules at the specified address：The API interface invocation conventions(https://github.com/nxtele/http-api-document/wiki/API%E6%8E%A5%E5%8F%A3%E8%B0%83%E7%94%A8%E7%BA%A6%E5%AE%9A)

Required Parameters

Parameters Header：

Parameter	Datatype	Mandatory	Example Value	Description
accessKey	String	yes	fme2na3kdi3ki	User identity identifier
ts	String	yes	1655710885431	The current timestamp of the request (units: milliseconds). The NXCLOUD server allows a maximum time deviation of 60 seconds for client requests
bizType	String	yes	9	The Zalo business type, set to a fixed value“9”
action	String	yes	mt	Send Zalo ZNS request，set to a fixed value“mt”
sign	String	yes	6e9506557d1f289501d333ee2c365826	The API input parameter signature，Signature algorithm

Body Parameters：

Parameter	Datatype	Mandatory	Example Value	Description
appkey	String	yes	pem28kje	Application appkey
phone	String	yes	86158xxxx1795	The Zalo phone number of the message recipient must include the country code. For example, 86158xxxx1795
functionType	String	yes	template	The Zalo message feature type, supporting the sending of the following types of features： template
messageData	JsonObject	yes	[Refer to the request example](#Example Request)	zalo message body parameters
drWebhook	String	no	https://xxxx/xxxx	Custom DR (Delivery Report) push address (prioritizes custom address for push); maximum length: 256 characters.
ext	String	Optional		Pass-through field for custom information. When filled, it will be returned as-is in receipts for success,failed,delivered,journey_acknowledged maximum length: 65,535 bytes.

The type of message feature

1. template：

• [Refer to the template request example](#Template Example Request)
• messageData Parameters：

Parameter	Datatype	Mandatory	Example Value	Description
templateId	String	yes	133214	ID of the template you want to use
journeyToken	String	no	xOZTk-513uRxumUxxxx.....	Sending a journey message is required
templateData	JsonObject	yes	[Refer to the template request example](#Example Request)	Zalo template variable parameters

---

Example Request

Template Example Request

body（application/json）parameters：

Normal ZNS messages

{
    "appkey": "cWF32dfsa",
    "functionType": "template",
    "phone": "843xxxx9945",
    "messageData": {
        "templateId":"3121234",
        "templateData": {
            "customer_name": "ZJC",
            "registered_code": "012432",
            "registered_date": "20/03/2020"
        }
    }
}

ZNS Journey messages

{
    "appkey": "cWF32dfsa",
    "functionType": "template",
    "phone": "843xxxx9945",
    "messageData": {
        "templateId":"3121777",
        "journeyToken":"xOZTk-513uRxumUxxxx.....",
        "templateData": {
            "customer_name": "ZJC",
            "registered_code": "012432",
            "registered_date": "20/03/2020"
        }
    }
}

Example Respond

Successful Example

{
    "code": 0,
    "message": "Success",
    "data": {
        "requestId": "zalomid.a1270d57c4274fa9917e0ad2629e3a99"
    },
    "traceId": "d9be566c3fff464190fd1082b8b67d3a"
}

Failure Example

{
    "code": -1,
    "message": "Failure",
    "traceId": "77f8709b545f4fee93fd7f098be9df04"
}

Explanation of response code

Code	Message	Description
0	Success
-1	Failure	Please contact technical personnel to troubleshoot the issue.
1000~100X	Authentication failed	For more information, please refer to the API authentication section.
1100	Customer does not exist / Status is unavailable	Account status abnormal. Please contact the business personnel to resolve the account issue.
1102	Insufficient balance	Insufficient account balance. Please contact the business personnel to recharge.
9000	Request parameter error	Parameter missing. Please check the required parameters.
9001	System business error	System business error. Please contact technical personnel to troubleshoot the issue.
9002	Phone number error	Illegal number. Please check the correctness of the number.
9003	Customer APP does not exist / Status is unavailable	Application status abnormal. Please contact the business personnel to address the cloud platform application creation/disabling issue.
9004	Customer APP does not have quotation	Application pricing missing. Please contact the business personnel to address the application pricing issue.
9005	Missing customer APP routes	Application routing missing. Please contact technical personnel to investigate the route.
17001	Zalo vendor template does not exist	The vendor template does not exist.
17002	Zalo vendor template status is unavailable	The vendor template is not available
9999	Unknown error	Please contact technical personnel to troubleshoot the issue.

Appendix

Guidelines

1. All messages must adhere to approved templates.
2. Text content can contain up to 400 characters.
3. You can include up to 8 parameters.
4. Delivery time for non-OTP message templates: <=7200 seconds; for OTP templates: <=15 seconds. Beyond these limits, no charges apply.