WeChat（微信）公式アカウントのテンプレートメッセージで notes フィールドが表示されない問題の調査と解決

問題の概要

WeChat公式アカウントのテスト号からテンプレートメッセージを送信しているとき、奇妙な現象に遭遇しました。テンプレートには6つのフィールドが定義されていますが、notes（備考）フィールドだけがどうしても表示されず、他の5つのフィールドはすべて正常に表示されます。

テンプレートの内容は以下のとおりです。

1
氏名：{{name.DATA}}
2
電話：{{phone.DATA}}
3
時間：{{time.DATA}}
4
項目：{{services.DATA}}
5
担当者：{{staff.DATA}}
6
備考：{{notes.DATA}}

API呼び出しは成功（errcode = 0）を返すのに、実際にWeChatで届くメッセージには最初の5行しか表示されず、備考行はまるごと消えてしまいます。

調査の流れ

1. フィールド数制限の検証

最初は「テスト号にはフィールド数の上限（最大5個）があるのでは？」と疑いました。しかし検証してみると：

• 「担当者」フィールドを削除して5個だけ送る → 備考は依然として表示されない
• フィールドを9個まで増やす → 備考を含むすべてのフィールドが表示される

結論：フィールド数の制限ではない。

2. 文字数制限の検証

公式ドキュメントによると、テンプレートメッセージは1行20文字以内、合計200文字以内とされています。テストデータはこの制限に遠く及びません。

結論：文字数の問題ではない。

3. 重要な法則の発見

繰り返しテストする中で、ある法則が見えてきました。

つまり、notes がテンプレートの最終行にあるときだけ表示が消えるのです。

4. フィールド名の検証

notes を最終行に置いたまま、フィールド名だけを変えてテスト：

notes と remark は表示されず、info、message は問題なく表示されます。

原因分析

WeChat公式アカウントのテンプレートメッセージAPIには、もともとトップレベルの remark パラメータが存在し、メッセージ末尾に「備考」として独自スタイルでレンダリングされていました。しかし 2023年3月30日、WeChatは以下のアナウンスを公開しました：

テンプレートメッセージでは備考（remark）フィールドを表示しなくなる

この仕様変更はトップレベルの remark パラメータだけでなく、フィールド名としての notes / remark にも影響しています。WeChat側で「備考」セマンティクスを持つフィールド名を内部的にマッチさせており、テンプレートの最終行に登場した場合、旧 remark 互換ロジックに乗ってサイレントに破棄される、というのが実態のようです。

要点：

• notes / remark はWeChatテンプレートメッセージにおける予約フィールド名
• 末尾に置くと旧 remark 互換ロジックに引っかかり、何の警告もなく削除される
• 末尾以外の位置に置くか、別の名前に変えれば正常に表示される

解決方法

方法1：フィールド名を変える（推奨）

最も無難な対応は、notes を予約名以外、たとえば message / info / desc などにリネームすることです。

1
氏名：{{name.DATA}}
2
電話：{{phone.DATA}}
3
時間：{{time.DATA}}
4
項目：{{services.DATA}}
5
担当者：{{staff.DATA}}
6
メッセージ：{{message.DATA}}

方法2：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
// WeChatが予約済みの「備考」フィールドとして扱い、表示しないため。
3
return {
4
  name,
5
  phone,
6
  time: timeRange,
7
  services,
8
  staff,
9
  message  // 旧: notes
10
};

まとめ

1. WeChat公式アカウントのテンプレートメッセージには予約フィールド名の仕組みが存在し、notes や remark などの「備考」セマンティクスを持つ名前は表示されない
2. これは2023年にWeChatがテンプレートメッセージの remark 表示を廃止したことに伴う互換挙動であり、表立ったドキュメントには明記されていない
3. 解決策はフィールド名を message / info / desc などに変更すること、または末尾に埋め草フィールドを追加すること
4. 「エラーは出ないが表示されない」系の問題は、フィールド数・位置・名前を1変数ずつ振って試すのが最短ルート

参考資料

• WeChat公式アカウント テンプレートメッセージ APIドキュメント
• テンプレートメッセージの文字数制限と remark 仕様変更について