Message Callback Service

Push ZaloZNS-related information to the provided webhook URL, including Message Receipt.

Message Receipt

After sending a Zalo ZNS message, receive a callback for the message status.

• URL：dr_webhook
• Method：POST
• Content-Type：application/json

Receipt Parameters

• body parameters:

Parameter	Type	Description
status	String	Receipt Status (success,delivered,journey_acknowledged,journey_time_out）
requestId	String	Message sending request ID
code	Number	status code(Status code description）
message	String	Status code information
sendTime	String	Send time
cost	Object	Fee Information (success,delivered,journey_acknowledged,journey_time_out show）
ext	String	Optional

• cost json obj:

Parameter	Type	Description
currency	String	currency
originalPrice	Number	original price

Receipt Examples

success

{
    "status": "success",
    "requestId": "zalomid.a941ccf8dd374dafxxxxxxacbe7a6ea5",
    "code": 0,
    "message": "Successfully sent.",
    "sendTime": "2024-05-01 10:12:39",
    "ext": "ext info",
    "cost": {
        "currency": "USD",
        "originalPrice": 4.1234
    },
    "zaloRes": {
        "sysMsg": "Successfully sent.",
        "cusMsg": "Successfully sent.",
        "error": 0,
        "message": "Success",
        "data": {
            "sent_time": "1714529559833",
            "sending_mode": "1",
            "msg_id": "5c4ee6axxxxxx9692026",
            "quota": {
                "remainingQuota": "4999",
                "dailyQuota": "5000"
            }
        }
    }
}

failed

{
    "status": "failed",
    "requestId": "zalomid.68d9cc28ba9546f797exxxxxx9333e23",
    "code": 17004,
    "message": "Zalo send error(Zalo account not existed)",
    "sendTime": "2024-10-30 10:34:40",
    "ext": "ext info",
    "zaloRes": {
        "sysMsg": "Zalo send error(Zalo account not existed)",
        "cusMsg": "Zalo send error(Zalo account not existed)",
        "error": -118,
        "message": "Zalo account not existed",
        "data": null
    }
}

delivered

{
    "status": "delivered",
    "requestId": "zalomid.a941ccf8dd374dafxxxxxxacbe7a6ea5",
    "code": 17003,
    "message": "Zalo message has delivered",
    "sendTime": "2023-07-13 15:12:11",
    "ext": "ext info"
}

journey_acknowledged

{
  "status": "journey_acknowledged",
  "requestId": "zalomid.a941ccf8dd374dafxxxxxxacbe7a6ea5",
  "code": 17006,
  "message": "The journey begins to be charged",
  "oaId": "30418xxxxxx05770721",
  "journeyId": "126052xxxx58967296",
  "appId": "33101xxxx80048",
  "timestamp": "1720602861913",
  "ext": "ext info",
  "cost": {
    "currency": "EUR",
    "originalPrice": 130
  }
}

journey_time_out

{
    "status": "journey_time_out",
    "code": 17007,
    "message": "Journey expires and has never been used",
    "journeyId": "126051xxxxxx4045952",
    "appId": "33101xxxxxx45180048",
    "oaId": "30418xxxxxx05770721",
    "timestamp": "1721206920581"
}

Status code description

code	message	Description
1100	Successfully sent.	Message submitted successfully submitted zalo.
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.
9999	Unknown error	Please contact technical personnel to troubleshoot the issue.
17003	Zalo message has delivered	message has delivered
17004	Zalo send error	Zalo official sending failure error message
17005	Zalo engine api timeout	Zalo send timeout
17005	The journey begins to be charged	Zalo Journey Token billing confirmation