Gửi tin giao dịch

Lưu ý:

  • Đối với các API sử dụng cho Shop thì API_KEY: <api_key>.Thông tin base_url của Shop

  • Đối với các API sử dụng cho Partner thì API_KEY: <shop_key>.Thông tin base_url của Partner

SendZNSTxn

post
Body
languagestring · enumOptionalPossible values:
oa_idstring · int64Optional
template_typestring · enumOptionalPossible values:
Responses
200
A successful response
application/json
post
POST /SendZNSTxn HTTP/1.1
Host: $BASE_URL.Zalo
Content-Type: application/json
Accept: */*
Content-Length: 458

{
  "language": "unknown",
  "message": {
    "buttons": [
      {
        "image_icon": "text",
        "payload": {
          "content": "text",
          "phone_code": "text",
          "url": "text"
        },
        "title": "text",
        "type": "unknown"
      }
    ],
    "content_banner": {
      "attachment_id": "text",
      "image_url": "text"
    },
    "content_header": {
      "align": "text",
      "content": "text"
    },
    "content_table": [
      {
        "key": "text",
        "style": "text",
        "value": "text"
      }
    ],
    "content_text": {
      "align": "text",
      "content": "text"
    }
  },
  "oa_id": "text",
  "recipient": {
    "user_id": "text"
  },
  "template_type": "unknown"
}
200

A successful response

{
  "message_id": "text"
}

Request:

curl --location 'BASE_URL.Zalo/SendZNSTxn' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $API_KEY' \
--data '{
  "language": "unknown",
  "message": {
    "buttons": [
      {
        "image_icon": "string",
        "payload": {
          "url": "string"
        },
        "title": "string",
        "type": "unknown"
      }
    ],
    "content_banner": {
      "attachment_id": "string"
    },
    "content_header": {
      "align": "string",
      "content": "string"
    },
    "content_table": [
      {
        "key": "string",
        "style": "string",
        "value": "string"
      }
    ],
    "content_text": {
      "align": "string",
      "content": "string"
    }
  },
  "oa_id": "string",
  "recipient": {
    "user_id": "string"
  },
  "template_type": "unknown"
}'

Response:

{
  "message_id": "string"
}

Cấu trúc body của request

Tham số
Kiểu dữ liệu
Mô tả

language

string

Ngôn ngữ sử dụng của tin Giá trị nhận vào:

  • language = VI

hoặc

  • language = EN

Khi chọn ngôn ngữ các nội dung mặc định của mẫu tin sẽ chuyển sang ngôn ngữ tương ứng

buttons

array

Các nút nhấn CTA (tùy chọn có hoặc không, tối đa 4 button)

image_icon

string

Có thể tryền:

  • image url của hình ảnh

  • attachment_id sau khi sử dụng API upload hình ảnh

  • để trống hoặc “default”: để sử dụng imaeg icon mặc định của Zalo

Lưu ý: Kích thước hình ảnh tối ưu: 100px * 100px

payload

object (mrButtonPayload)

content phone_code url

title

string

Tiêu đề của button

Lưu ý: Tiêu đề không được vượt quá 35 ký tự

type

string (thTemplateTxnButtonType)

Loại action sẽ thực hiện khi người quan tâm bấm vào oa.open.url: Data là một Url sẽ được mở trong ứng dụng Zalo khi người quan tâm bấm vào button. Ví dụ:

{
    "image_icon": "string",
    "payload": {
        "url": "string"
    },
    "title": "string",
    "type": "unknown"
}
  • Chú ý: Giới hạn cho thuộc tính "title" là 100 kí tự.

oa.query.show: Data là một chuỗi ký tự ví dụ “#callback_data”. Khi người quan tâm bấm vào button, hệ thống sẽ gửi một tin nhắn có nội dung chứa trong data từ người quan tâm đến Official Account. Tin nhắn này sẽ hiện trên cửa sổ chat trên máy của người quan tâm.

  • Chú ý:

    • Giới hạn cho thuộc tính "title" là 100 kí tự.

    • Giới hạn cho thuộc tính "payload" là 1000 kí tự.

oa.query.hide: Data là một chuỗi ký tự ví dụ “#callback_data”. Khi người quan tâm bấm vào button, hệ thống sẽ gửi một tin nhắn có nội dung chứa trong data từ người quan tâm đến Official Account. Tin nhắn này sẽ bị ẩn trên cửa sổ chat trên máy của người quan tâm.

  • Chú ý:

    • Giới hạn cho thuộc tính "title" là 100 kí tự.

    • Giới hạn cho thuộc tính "payload" là 1000 kí tự.

oa.open.sms: Data đối tượng json chứa 2 thuộc tính “content” và “phoneCode”. Ví dụ:

{
    "payload": {
        "content": "sting",
        "phone_code": "string"
    },
    "title": "OPEN SMS",
    "type": "oa.open.sms"
}

Khi người quan tâm click vào button, cửa sổ sms trên điện thoại của người quan tâm sẽ được mở với 2 thông tin sẵn có là phone code và nội dung tin nhắn trong data.

  • Chú ý:

    • Giới hạn cho thuộc tính "title" là 100 kí tự.

    • Thuộc tính "content" có giới hạn là 160 kí tự.

oa.open.phone: Data số điện thoại sẽ nhập vào khi bật ứng dụng gọi điện, ví dụ:

{
    "payload": {
        "phone_code": "string"
    },
    "title": "OPEN PHONE",
    "type": "oa.open.phone"
}

Khi người quan tâm click vào button, cửa sổ call trên điện thoại của người quan tâm sẽ được mở với thông tin sẵn có là phone number trong data.

  • Chú ý: Giới hạn cho thuộc tính "title" là 100 kí tự.

content_banner

object (mrContentBanner)

attachment_id: ID của ảnh bạn muốn sử dụng (nhận được thông qua API upload file) image_url: Đường dẫn đến ảnh Các định dạng ảnh hỗ trợ: jpg và png

Dung lượng tối đa: 1MB Tỉ lệ kích thước ảnh (height :width): từ 1:5 đến 1:1 (ảnh vuông)

Lưu ý: chỉ sử dụng 1 trong 2 biến image_url hoặc attachment_id

content_header

object (mrContentHeader)

content: Nội dung của header, tối đa 100 ký tự. align: Chấp nhận 3 giá trị

  • left (hoặc để trống): canh lề bên trái

  • center: canh lề giữa

  • right: canh lề bên phải

content_table

Array

Cấu trúc 1 phần tử trong table là:

{
  "key": "giá trị của key", // maxlength = 35
  "value": "giá trị của value" // maxlength = 100
}
  • Trong đó bắt buộc phải có 1 trong 2 phần tử dưới đây:

    • VN:

      {
        "key": "Mã...", // bắt đầu là "Mã", dùng định danh người nhận
        "value": "Giá trị tự do"
      }

      EN:

      {
        "key": "...Code...", // bắt buộc có chứa "Code" trong key
        "value": "Giá trị tự do"
      }

    hoặc

    • VN:

      {
        "key": "Tên khách hàng", // key có giá trị cố định "Tên khách hàng"
        "value": "Giá trị tự do"
      }

      EN:

      {
        "key": "Customer Name", // key có giá trị cố định "Customer Name"
        "value": "Giá trị tự do"
      }
  • Key "Trạng thái" / "Status" là key duy nhất hiện tại được phép sử dụng tham số "Style":

    • VN:

      {
         "key": "Trạng thái" // key có giá trị cố định "Trạng thái"
         "value": "Giá trị tự do"
         "style": "yellow" // Giá trị hợp lệ: green, blue, yellow, red, grey
      }

      EN:

      {
         "key": "Status" // key có giá trị cố định "Status"
         "value": "Giá trị tự do"
         "style": "yellow" // Giá trị hợp lệ: green, blue, yellow, red, grey
      }
    • Các giá trị của "style": green, blue, yellow, red, grey

  • Ngoài các phần tử hệ thống quy định như trên, nhà phát triển có thể khai báo thêm tối đa 5 phần tử tùy ý.

content_text

object (mrContentText)

content: Nội dung của header, tối đa 100 ký tự. align: Chấp nhận 3 giá trị

  • left (hoặc để trống): canh lề bên trái

  • center: canh lề gi

oa_id

string

ID của OA

recipient

object (mrRecipient)

user_id: ID của người dùng Zalo

template_type

string

Mã template
Loại tin (VN)
Message Type (EN)
Ngành áp dụng

transaction_billing

Hóa đơn

Billing

Tất cả

transaction_order

Đơn hàng

Order

Tất cả

transaction_reward

Tích điểm

Reward

Tất cả

transaction_contract

Hợp đồng

Contract

Tất cả

transaction_booking

Lịch hẹn

Booking

Tất cả

transaction_membership

Thành viên

Membership

Tất cả

transaction_event

Sự kiện

Event

Tất cả

transaction_transaction

Giao dịch

Transaction

Tất cả

transaction_account

Tài khoản

Account

Tất cả

transaction_internal

Nội bộ

Internal

Tất cả

transaction_partnership

Đối tác

Partnership

Tất cả

transaction_education

Học vụ

Education

Giáo dục và đào tạo

transaction_rating

Đánh giá

Rating

Tất cả

Cấu trúc thuộc tính dữ liệu trả về

Tham số
Kiểu dữ liệu
Mô tả

msg_id

string

ID của thông báo

Last updated