Why the notes Field Is Missing in WeChat Official Account Template Messages — Debugging and Fix

Problem

While sending template messages from a WeChat Official Account sandbox (test) account, I hit a strange issue: the template defines 6 fields, but the notes field is never displayed. The other 5 fields render perfectly.

The template content:

1
Name: {{name.DATA}}
2
Phone: {{phone.DATA}}
3
Time: {{time.DATA}}
4
Service: {{services.DATA}}
5
Staff: {{staff.DATA}}
6
Notes: {{notes.DATA}}

The API call returns success, but only the first 5 lines appear in the actual WeChat message — the notes line is gone, including the “Notes:” label itself.

Debugging Process

1. Rule out the field count limit

My first guess was that sandbox accounts have a field count limit (max 5). Tested:

Drop the “Staff” field so only 5 fields are sent → notes still doesn’t show
Add more fields up to 9 → everything, including notes, shows up

Conclusion: not a field count limit.

2. Rule out the length limit

Per official docs, each line in a template message is capped at 20 characters and the total at 200. My test data was nowhere near that.

Conclusion: not a length issue.

3. Spot the real pattern

After many trials a clear pattern emerged:

Number of fields	Position of notes	notes shown?
6 fields	last	No
9 fields	6th (not last)	Yes
7 fields	6th (not last)	Yes

As long as notes is the last field in the template, it disappears. Move it off the last line and it comes back.

4. Test the field name itself

Keep notes in the last position, swap the name:

Field name	Displayed?
notes	No
remark	No
info	Yes
message	Yes

notes and remark both disappear; info and message work fine.

Root Cause

The WeChat Official Account template message API originally supported a top-level remark parameter rendered as a “remark/footer” line at the bottom of the message. On March 30, 2023, WeChat published a notice:

Template messages will no longer display the remark field.

That deprecation didn’t only target the top-level remark parameter. WeChat also performs semantic matching on field names like notes and remark — when such a name appears as the last field of the template, it’s silently dropped as the legacy “remark” slot.

In short:

notes and remark are reserved field names in WeChat template messages.
When they appear at the end of a template, they trigger the legacy remark-compat path and are dropped without warning.
Move them away from the last position, or use a different name, and they render normally.

Solutions

Option 1: Rename the field (recommended)

The cleanest fix: rename notes to something outside the reserved set, such as message, info, desc, etc.

1
Name: {{name.DATA}}
2
Phone: {{phone.DATA}}
3
Time: {{time.DATA}}
4
Service: {{services.DATA}}
5
Staff: {{staff.DATA}}
6
Message: {{message.DATA}}

Option 2: Append a filler field after notes

If renaming isn’t an option (template already audited and used by multiple integrations), tack on a filler field so notes is no longer the last line:

1
Name: {{name.DATA}}
2
Phone: {{phone.DATA}}
3
Time: {{time.DATA}}
4
Service: {{services.DATA}}
5
Staff: {{staff.DATA}}
6
Notes: {{notes.DATA}}
7
Other: {{other.DATA}}

You can send other as an empty string or a placeholder.

Code change

In the backend payload, rename notes to message:

1
// IMPORTANT: don't use `notes` as a field name.
2
// WeChat treats it as the reserved "remark" field and drops it silently.
3
return {
4
  name,
5
  phone,
6
  time: timeRange,
7
  services,
8
  staff,
9
  message  // was: notes
10
};

Takeaways

WeChat Official Account template messages have reserved field names. notes, remark, and similar “remark-like” names get treated as the legacy remark slot and aren’t displayed.
This is a side effect of WeChat’s 2023 deprecation of the remark field — template messages no longer show remark content.
The fix is to avoid these reserved names and use neutral ones like message, info, or desc.
When you hit a “no error, but not visible” issue like this, vary the field count, position, and name one variable at a time — you’ll find the pattern faster than you’ll find docs about it.