微信公眾號範本訊息 notes 欄位不顯示問題排查與解決

問題描述

在使用微信公眾號測試號發送範本訊息時，遇到一個奇怪的問題：範本中定義了6個欄位，但 notes（備註）欄位始終不顯示，其他5個欄位都能正常顯示。

範本內容如下：

1
姓名：{{name.DATA}}
2
電話：{{phone.DATA}}
3
時間：{{time.DATA}}
4
項目：{{services.DATA}}
5
員工：{{staff.DATA}}
6
備註：{{notes.DATA}}

API 呼叫返回成功，但微信訊息中只顯示前5行，備註始終不出現。

排查過程

1. 排除欄位數量限制

最初懷疑是微信測試號有欄位數量限制（最多5個欄位）。透過測試發現：

• 去掉「員工」欄位，只發5個欄位 → 備註仍然不顯示
• 添加更多欄位到9個 → 所有欄位包括備註都顯示了

結論：不是欄位數量限制。

2. 排除字元長度限制

根據微信官方文件，範本訊息每行內容不超過20字元，總內容不超過200字元。測試資料遠未超過限制。

結論：不是字元長度問題。

3. 發現關鍵規律

透過反覆測試發現一個規律：

當 notes 是範本的最後一個欄位時，它不會顯示。

4. 驗證 notes 欄位名問題

將 notes 替換為其他欄位名測試：

notes 和 remark 都不顯示，而 info、message 可以正常顯示。

原因分析

微信公眾號範本訊息 API 原本支援一個 remark 參數，用於在訊息底部顯示備註資訊。但從 2023年3月30日 起，微信官方發布公告：

範本訊息不再展示備註（remark）欄位

微信對 notes、remark 等欄位名進行了特殊處理，將其識別為「備註」類欄位，因此不予顯示。這是微信的保留欄位名限制。

解決方案

方案一：更換欄位名（推薦）

將 notes 改為其他名稱，如 message、info、desc 等：

1
姓名：{{name.DATA}}
2
電話：{{phone.DATA}}
3
時間：{{time.DATA}}
4
項目：{{services.DATA}}
5
員工：{{staff.DATA}}
6
留言：{{message.DATA}}

方案二：在 notes 後添加佔位欄位

在 notes 後面添加一個佔位欄位，使其不再是最後一個欄位：

1
姓名：{{name.DATA}}
2
電話：{{phone.DATA}}
3
時間：{{time.DATA}}
4
項目：{{services.DATA}}
5
員工：{{staff.DATA}}
6
備註：{{notes.DATA}}
7
其他：{{other.DATA}}

發送時 other 欄位可以不傳值或傳空值。

程式碼修改

後端發送通知資料時，將欄位名從 notes 改為 message：

1
// 注意：不能使用 notes 作為欄位名，微信會將其識別為保留的「備註」欄位而不顯示
2
return {
3
  name,
4
  phone,
5
  time: timeRange,
6
  services,
7
  staff,
8
  message  // 原來是 notes
9
};

總結

1. 微信公眾號範本訊息有保留欄位名限制，notes、remark 等會被識別為「備註」欄位而不顯示
2. 這是 2023 年微信政策調整的結果，範本訊息不再展示備註內容
3. 解決方案是避免使用這些保留欄位名，改用 message、info 等普通名稱
4. 排查此類問題時，可以透過添加/刪除欄位、更換欄位名等方式逐步定位

參考資料

• 微信公眾平台範本訊息介面文件
• 範本訊息字數限制說明