WeChat Tài khoản Chính thức — trường «notes» trong Template Message không hiển thị — phân tích và giải pháp

Vấn đề

Khi gửi tin nhắn mẫu (Template Message) từ tài khoản test (sandbox) của WeChat Tài khoản Chính thức, tôi gặp một hiện tượng kỳ lạ: mẫu định nghĩa 6 trường, nhưng trường notes (ghi chú) không bao giờ hiển thị. 5 trường còn lại hiển thị bình thường.

Nội dung mẫu:

1
Tên: {{name.DATA}}
2
Điện thoại: {{phone.DATA}}
3
Thời gian: {{time.DATA}}
4
Dịch vụ: {{services.DATA}}
5
Nhân viên: {{staff.DATA}}
6
Ghi chú: {{notes.DATA}}

Lệnh gọi API trả về thành công (errcode = 0), nhưng tin nhắn WeChat thực nhận chỉ hiển thị 5 dòng đầu — dòng ghi chú biến mất hoàn toàn, kể cả nhãn “Ghi chú”.

Quá trình điều tra

1. Loại bỏ giới hạn số lượng trường

Giả thuyết đầu tiên: tài khoản sandbox giới hạn tối đa 5 trường. Kiểm tra:

Bỏ trường “Nhân viên”, chỉ gửi 5 trường → notes vẫn không hiển thị
Tăng lên 9 trường → mọi trường, kể cả notes, đều hiển thị

Kết luận: không phải giới hạn số lượng trường.

2. Loại bỏ giới hạn độ dài ký tự

Theo tài liệu chính thức, mỗi dòng tin nhắn mẫu giới hạn 20 ký tự, tổng nội dung 200 ký tự. Dữ liệu thử của tôi thấp hơn rất nhiều.

Kết luận: cũng không phải vấn đề độ dài.

3. Tìm ra quy luật thật sự

Sau nhiều lần thử, hiện ra một quy luật rõ ràng:

Số lượng trường	Vị trí của notes	notes có hiển thị?
6 trường	dòng cuối	Không
9 trường	thứ 6 (không phải cuối)	Có
7 trường	thứ 6 (không phải cuối)	Có

Tức là: chừng nào notes còn là dòng cuối của mẫu, nó biến mất. Chỉ cần có một trường nữa đứng sau, nó hiện lại bình thường.

4. Kiểm tra chính tên trường

Giữ notes ở vị trí cuối, chỉ đổi tên:

Tên trường	Hiển thị?
notes	Không
remark	Không
info	Có
message	Có

notes và remark đều biến mất; info, message hiển thị bình thường.

Nguyên nhân

API tin nhắn mẫu của WeChat Tài khoản Chính thức ban đầu hỗ trợ tham số remark ở cấp cao nhất, được render thành “ghi chú” ở cuối tin nhắn. Vào ngày 30 tháng 3 năm 2023, WeChat phát hành thông báo:

Tin nhắn mẫu sẽ không còn hiển thị trường remark.

Việc loại bỏ này không chỉ ảnh hưởng tham số remark cấp cao nhất. WeChat còn thực hiện đối sánh ngữ nghĩa với tên trường như notes và remark — khi tên kiểu này xuất hiện ở vị trí trường cuối cùng trong mẫu, nó sẽ bị loại bỏ âm thầm theo nhánh tương thích với remark cũ.

Tóm lại:

notes và remark là tên trường được dành riêng (reserved) trong tin nhắn mẫu của WeChat.
Khi đặt ở vị trí cuối, chúng kích hoạt nhánh tương thích remark cũ và bị xoá không có cảnh báo.
Đặt ở vị trí khác, hoặc đổi tên, đều hiển thị bình thường.

Giải pháp

Cách 1: đổi tên trường (khuyến nghị)

Cách gọn gàng nhất: đổi notes sang một tên không nằm trong danh sách dành riêng, ví dụ message, info, desc v.v.

1
Tên: {{name.DATA}}
2
Điện thoại: {{phone.DATA}}
3
Thời gian: {{time.DATA}}
4
Dịch vụ: {{services.DATA}}
5
Nhân viên: {{staff.DATA}}
6
Tin nhắn: {{message.DATA}}

Cách 2: thêm trường lấp chỗ sau notes

Nếu không thể đổi tên (mẫu đã được duyệt, đang chạy production và được nhiều hệ thống tham chiếu), hãy thêm một trường “lấp chỗ” sau notes để nó không còn là dòng cuối:

1
Tên: {{name.DATA}}
2
Điện thoại: {{phone.DATA}}
3
Thời gian: {{time.DATA}}
4
Dịch vụ: {{services.DATA}}
5
Nhân viên: {{staff.DATA}}
6
Ghi chú: {{notes.DATA}}
7
Khác: {{other.DATA}}

Khi gửi, trường other có thể truyền chuỗi rỗng hoặc placeholder.

Sửa code

Ở backend, đổi tên trường từ notes thành message trong payload:

1
// QUAN TRỌNG: không dùng notes làm tên trường.
2
// WeChat coi đây là trường "remark" dành riêng và loại bỏ âm thầm.
3
return {
4
  name,
5
  phone,
6
  time: timeRange,
7
  services,
8
  staff,
9
  message  // trước đây: notes
10
};

Tổng kết

Tin nhắn mẫu của WeChat Tài khoản Chính thức có cơ chế tên trường dành riêng. Những tên mang ngữ nghĩa “remark” như notes, remark v.v. bị diễn giải là vị trí ghi chú cũ và không hiển thị.
Đây là tác dụng phụ của việc WeChat loại bỏ trường remark trong tin nhắn mẫu vào năm 2023 — và không được tài liệu hoá nổi bật.
Cách khắc phục: dùng tên trung tính như message, info, desc, hoặc thêm trường lấp chỗ sau notes.
Với các bug kiểu “không có lỗi nhưng không hiển thị”, thay đổi số lượng trường, vị trí và tên từng biến một thường nhanh hơn là đi tìm tài liệu.