Tin Zalo giao dịch

HTTP request

POST https://rest.esms.vn/mainservice.svc/json/SendZaloFollowerMessage_V5_post_json/

• Content Type: text/plain

• Response Type: application/json

curl --location 'https://rest.esms.vn/mainservice.svc/json/SendZaloFollowerMessage_V5_post_json/' \
--header 'Content-Type: text/plain' \
--data '{
    "ApiKey": "{{ApiKey}}",
    "SecretKey": "{{SecretKey}}",
    "OAID": "{{OAID}}",
    "RequestId": "96accf59-0c41-4bc7-a5c4-4a466c2e41c2", 
    "Payload": {
        "recipient": {
            "user_id": "{{user_id}}"
        },
        "message": {
            "attachment": {
                "type": "template",
                "payload": {
                    "template_type": "transaction_order",
                    "language": "VI",
                    "elements": [
                        {
                            "image_url": "https://minio.esms.vn/blogimg/agent-1/BlogImg/full_cccc34d4-3a46-4644-8613-1b226203c5d5.png",
                            "type": "banner"
                        },
                        {
                            "type": "header",
                            "content": "Trạng thái đơn hàng",
                            "align": "left"
                        },
                        {
                            "type": "text",
                            "align": "left",
                            "content": "• Cảm ơn bạn đã mua hàng tại cửa hàng.<br>• Thông tin đơn hàng của bạn như sau:"
                        },
                        {
                            "type": "table",
                            "content": [
                                {
                                    "value": "eSMS-001",
                                    "key": "Mã khách hàng"
                                },
                                {
                                    "style": "yellow",
                                    "value": "Đang giao",
                                    "key": "Trạng thái"
                                },
                                {
                                    "value": "250,000đ",
                                    "key": "Giá tiền"
                                }
                            ]
                        },
                        {
                            "type": "text",
                            "align": "center",
                            "content": "📲 Lưu ý điện thoại. Xin cảm ơn!"
                        }
                    ],
                    "buttons": [
                        {
                            "title": "Kiểm tra lộ trình",
                            "image_icon": "https://img.icons8.com/?size=100&id=kJlyCVWJrclv&format=png&color=000000",
                            "type": "oa.open.url",
                            "payload": {
                                "url": "https://esms.vn/huong-dan/huong-dan-tich-hop/huong-dan-tich-hop-api-cua-esms-vao-website"
                            }
                        },
                        {
                            "title": "Xem lại giỏ hàng",
                            "image_icon": "https://img.icons8.com/?size=100&id=S2Z1vzGMFT1v&format=png&color=000000",
                            "type": "oa.open.url",
                            "payload": {
                                "url": "https://esms.vn/huong-dan/huong-dan-su-dung"
                            }
                        },
                        {
                            "title": "Liên hệ tổng đài",
                            "image_icon": "https://img.icons8.com/?size=100&id=KKBDB20a4V6t&format=png&color=000000",
                            "type": "oa.open.phone",
                            "payload": {
                                "phone_code": "0901888484"
                            }
                        }
                    ]
                }
            }
        }
    }
}'

• Cấu trúc body của request:

Tham số	Kiểu dữ liệu	Tính bắt buộc	Định nghĩa
ApiKey	string		ApiKey của tài khoản.
SecretKey	string		Secretkey của tài khoản.
OAID	string		Zalo OA ID, là ID của trang Zalo Offical Account của doanh nghiệp. Doanh nghiệp cần đăng nhập vào trang quản trị của Zalo OA để lấy phần Zalo OA ID này. Chú ý: sẽ phải đăng ký trước khi sử dụng.
RequestId	string		ID đối tác truyền sang để chặn trùng và đối soát khi cần. Độ dài tối đa 50 ký tự. Mỗi RequestId truyền sang có hiệu lực chặn trong 24h.
Sandbox	string		1: Tin gửi ở môi trường test, dùng để kiểm tra kết nối và các thông số tích hợp, không về tin nhắn, không trừ tiền. 0: Tin gửi ở môi trường bình thường, có về tin nhắn.
CallbackUrl	string		eSMS sẽ trả về kết quả của tin nhắn này. Xem body mẫu ở đây. Xem chi tiết ở đây.
SendDate	string		Thời gian hẹn gửi của tin. Không truyền khi tin muốn tin nhắn gửi đi liền. Định dạng: yyyy-mm-dd hh:MM:ss
Payload	Object		Chứa nội dung cần gửi

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

Tham số	Kiểu dữ liệu	Tính bắt buộc	Định nghĩa
user_id	string		ID của người nhận.

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

Tham số	Kiểu dữ liệu	Tính bắt buộc	Định nghĩa
attachment	object		Attachment cần gửi

Cấu trúc thuộc tính message.attachment

Tham số	Kiểu dữ liệu	Tính bắt buộc	Định nghĩa
type	string		Loại attachment Giá trị nhận vào bắt buộc: type = template
payload	object		Chứa payload của attachment muốn gửi.

Cấu trúc thuộc tính message.attachment.payload

Tham số	Kiểu dữ liệu	Tính bắt buộc	Định nghĩa
template_type	string		Xem thêm mục Tham số message.attachment.payload.template_type bên dưới
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
elements	array		Các đối tượng của template. Xem thêm mục message.attachment.payload.elements bên dưới
buttons	array		Các nút nhấn CTA (tùy chọn có hoặc không, tối đa 4 button) Xem thêm mục message.attachment.payload.buttons bên dưới

Tham số message.attachment.payload.template_type

STT	Mã template	Loại tin (VN)	Message Type (EN)
1	transaction_billing	Hóa đơn	Billing
2	transaction_order	Đơn hàng	Order
3	transaction_reward	Tích điểm	Reward
4	transaction_contract	Hợp đồng	Contract
5	transaction_booking	Lịch hẹn	Booking
6	transaction_membership	Thành viên	Membership
7	transaction_event	Sự kiện	Event
8	transaction_transaction	Giao dịch	Transaction
9	transaction_account	Tài khoản	Account
10	transaction_internal	Nội bộ	Internal
11	transaction_partnership	Đối tác	Partnership
12	transaction_education	Học vụ	Education
13	transaction_rating	Đánh giá	Rating

Cấu trúc tham số message.attachment.payload.elements

Type	Thuộc tính	Kiểu dữ liệu	Tính bắt buộc	Định nghĩa
banner	image_url	string		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)
header	content	string		Nội dung của header, tối đa 100 ký tự.
	align	string		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
text (lưu ý tối đa được 2 đoạn text)	content	string		Nội dung của text, tối đa 250 ký tự mỗi đoạn
	align	string		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
table	content	array		Cấu trúc 1 phần tử trong table là: { "key": "giá trị của key" // maxlength = 25 "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: VI: { "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: VI: { "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 } ****Lưu ý: có thể khai báo thêm tối đa 5 phần tử tùy ý.

Cấu trúc tham số message.attachment.payload.buttons

Thuộc tính	Kiểu dữ liệu	Tính bắt buộc	Định nghĩa
title	string		Tiêu đề của button Lưu ý: Tiêu đề không được vượt quá 35 ký tự
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
type, payload	object		Xem thêm mục Cấu trúc payload cho các loại action được hỗ trợ bên dưới

Cấu trúc payload cho các loại action được hỗ trợ

Giá trị type	Kiểu dữ liệu của payload	Giá trị payload và kết quả khi người quan tâm bấm vào
oa.open.url	string	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ụ: { "title": "OPEN URL", "payload" : { "url": "https://developers.zalo.me/" }, "type": "oa.open.url" } Chú ý: Giới hạn cho thuộc tính "title" là 100 kí tự.
oa.query.show	string	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. Ví dụ: { "title": "QUERY SHOW", "type": "oa.query.show", "payload": "#callback_data" } 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	string	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. Ví dụ: { "title": "QUERY HIDE", "type": "oa.query.hide", "payload": "#callback_data" } 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	object	Data đối tượng json chứa 2 thuộc tính “content” và “phoneCode”. Ví dụ: { "title": "OPEN SMS", "type": "oa.open.sms", "payload": { "content":"alo", "phone_code":"84919018791" } } 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	object	Data số điện thoại sẽ nhập vào khi bật ứng dụng gọi điện, ví dụ: { "title": "OPEN PHONE", "type": "oa.open.phone", "payload":{ "phone_code":"84919018791" } } 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ự.

• Response:

100

{
    "CodeResult": "100",
    "CountRegenerate": 0,
    "SMSID": "d8e0f1f0702544b2acb456ca9ccfd111250"
}

Request hợp lệ.

101

• Cấu trúc body của response:

Thuốc tính	Kiểu dữ liệu	Mô tả
CodeResult	string	Request được gửi đến ESMS thành công. Lưu ý: Mã phản hồi 100 chỉ xác nhận rằng yêu cầu đã được gửi thành công đến hệ thống ESMS, không phản ánh việc tin nhắn đã được gửi đến số điện thoại người nhận hay chưa. Để theo dõi trạng thái cuối cùng của tin nhắn, quý khách vui lòng truyền thêm tham số CallbackUrl; hệ thống ESMS sẽ tự động gửi phản hồi (callback) đến địa chỉ này khi có trạng thái cuối của tin.
SMSID	string	ID tin nhắn do esms trả về.
ErrorMessage	string	Thông tin lỗi trả về (nếu có lỗi).

• Thông tin chi tiết mã lỗi xem ở bảng: Mã lỗi .

• Lấy code mẫu các ngôn ngữ trên Postman: Link code mẫu.