API gửi tin nhắn hành trình (Journey Message)

Cập nhật lần cuối:20/8/2026

HTTP Request

URL	https://openapi.zalo.me/v3.0/oa/message/platformtemplate
Method	POST
Content Type	application/json
Response Type	application/json

Example request

curl --location 'https://openapi.zalo.me/v3.0/oa/message/platformtemplate' \
--header 'access_token: <your_oa_access_token>' \
--header 'oa_messsage_token: <your_oa_messsage_token>' \
--header 'Content-Type: application/json' \
--data '{
  "user_id": "2195265126953705800",
  "template_id": "104000",
  "template_data": {
    "service_name": "Internet",
    "package_name": "Gói Internet Fiber 100Mbps",
    "amount_money": "500.000đ",
    "time": "12:03 24/06/26",
    "transaction_code": "TX9920261206",
    "order_code": "TX9920261206",
    "buttons": [
      {
        "title": "Xem chi tiết",
        "url": "https://zalo.me/s/napdienthoai"
      }
    ]
  }
}'

Tham số header

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
access_token	string	TRUE	Token cho phép ứng dụng đại diện OA gọi API. Xem chi tiết cách lấy access token tại đây.
oa_messsage_token	string	TRUE	Token gửi tin do OA cấp khi user tương tác có ý nghĩa trong Mini App (oaMessageToken)

Cấu trúc body request

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
user_id	string	TRUE	ID của người nhận Định danh người dùng theo OA - dùng để xác thực cho miniapp (nhận được thông qua API truy xuất chi tiết người dùng, API truy xuất danh sách người dùng, các event liên quan đến người dùng).
template_id	string	TRUE	ID của predefined template muốn sử dụng. Tham khảo danh sách predefined template tại đây
template_data	JSON object	TRUE	Các thuộc tính của predefined template muốn sử dụng Lưu ý: Cấu trúc template_data được quy định riêng ứng với từng template. Tham khảo tại đây

Example response

{
  "data": {
    "message_id": "63ecf43f0df7dba892e6",
    "user_id": "2512523625412515"
  },
  "error": 0,
  "message": "Success"
}

Cấu trúc thuộc tính data

Thuộc tính	Kiểu dữ liệu	Mô tả
message_id	string	ID của thông báo
user_id	string	ID của người nhận

Mã lỗi

Mã lỗi	Mô tả	Hướng dẫn xử lý
0	Gửi thành công
-108	user_id không hợp lệ
-118	user_id không thuộc OA đang thực hiện gửi tin
-122	Format body của request không hợp lệ	Xem chi tiết quy định tại đây
-124	access_token không hợp lệ	Xem chi tiết cách lấy access token tại đây
-604	oa_message_token vượt quá quota	Sử dụng oa_message_token khác
-603	oa_message_token không khả dụng	Kiểm tra lại oa_message_token/ thời hạn của token
-602	template_id không khả dụng	Tham khảo template_id được cho phép tại đây
-601	Param không phù hợp với template (thiếu/thừa field, thừa ký tự, sai format,...)	Tham khảo param mẫu & yêu cầu param ứng với từng template_id tại đây