WeChat Akun Resmi — Field «notes» di Template Message Tidak Muncul — Analisis dan Solusi

Masalah

Saat mengirim template message dari akun uji coba (sandbox) WeChat Akun Resmi, saya menemui kasus aneh: template mendefinisikan 6 field, tetapi field notes (catatan) selalu tidak ditampilkan. Lima field lainnya tampil normal.

Isi template:

1
Nama: {{name.DATA}}
2
Telepon: {{phone.DATA}}
3
Waktu: {{time.DATA}}
4
Layanan: {{services.DATA}}
5
Staf: {{staff.DATA}}
6
Catatan: {{notes.DATA}}

Pemanggilan API mengembalikan sukses (errcode = 0), namun di pesan WeChat yang diterima hanya 5 baris pertama yang muncul — baris catatan hilang seluruhnya, termasuk label “Catatan”.

Proses Investigasi

1. Mengeliminasi batas jumlah field

Hipotesis pertama: akun sandbox dibatasi maksimum 5 field. Diuji:

Hilangkan field “Staf” dan kirim hanya 5 field → notes tetap tidak muncul
Tambah hingga 9 field → semua field, termasuk notes, muncul

Kesimpulan: bukan batas jumlah field.

2. Mengeliminasi batas panjang karakter

Menurut dokumentasi resmi, setiap baris template message dibatasi 20 karakter dan total 200 karakter. Data uji jauh di bawah batas tersebut.

Kesimpulan: bukan masalah panjang karakter.

3. Menemukan pola sebenarnya

Setelah pengujian berulang, muncul pola yang jelas:

Jumlah field	Posisi notes	notes muncul?
6 field	terakhir	Tidak
9 field	ke-6 (bukan terakhir)	Ya
7 field	ke-6 (bukan terakhir)	Ya

Artinya: selama notes adalah baris terakhir template, ia menghilang. Begitu ada field setelahnya, ia muncul kembali.

4. Menguji nama field

notes tetap pada posisi terakhir, hanya namanya yang diganti:

Nama field	Muncul?
notes	Tidak
remark	Tidak
info	Ya
message	Ya

notes dan remark sama-sama tidak muncul; info dan message tampil normal.

Analisis Penyebab

API template message WeChat Akun Resmi awalnya mendukung parameter remark di level paling atas yang dirender sebagai “catatan” di bagian bawah pesan. Pada 30 Maret 2023, WeChat merilis pengumuman:

Template message tidak akan lagi menampilkan field remark.

Pencabutan ini bukan hanya menyasar parameter remark di level atas. WeChat juga melakukan pencocokan semantik pada nama field seperti notes dan remark — ketika nama tersebut muncul sebagai field terakhir dalam template, ia akan dibuang diam-diam melalui jalur kompatibilitas remark lama.

Singkatnya:

notes dan remark adalah nama field yang dipesan (reserved) di template message WeChat.
Di posisi terakhir, mereka memicu logika kompatibilitas remark lama dan dihapus tanpa peringatan.
Di posisi lain atau dengan nama lain, mereka tampil normal.

Solusi

Cara 1: Ganti nama field (disarankan)

Solusi paling bersih: ganti notes ke nama yang tidak masuk daftar reserved, misalnya message, info, desc, dll.

1
Nama: {{name.DATA}}
2
Telepon: {{phone.DATA}}
3
Waktu: {{time.DATA}}
4
Layanan: {{services.DATA}}
5
Staf: {{staff.DATA}}
6
Pesan: {{message.DATA}}

Cara 2: Tambahkan field pengisi setelah notes

Jika mengganti nama tidak memungkinkan (template sudah lolos audit, di produksi, dipakai banyak integrasi), tambahkan field “pengisi” setelah notes agar bukan baris terakhir lagi:

1
Nama: {{name.DATA}}
2
Telepon: {{phone.DATA}}
3
Waktu: {{time.DATA}}
4
Layanan: {{services.DATA}}
5
Staf: {{staff.DATA}}
6
Catatan: {{notes.DATA}}
7
Lainnya: {{other.DATA}}

Saat pengiriman, field other boleh dikirim dengan string kosong atau placeholder.

Perubahan Kode

Pada backend, ganti nama field notes menjadi message di payload:

1
// PENTING: jangan gunakan notes sebagai nama field.
2
// WeChat memperlakukannya sebagai field "remark" yang dipesan dan menghapusnya tanpa peringatan.
3
return {
4
  name,
5
  phone,
6
  time: timeRange,
7
  services,
8
  staff,
9
  message  // sebelumnya: notes
10
};

Kesimpulan

Template message WeChat Akun Resmi memiliki nama field yang dipesan. Nama-nama dengan semantik “remark” (notes, remark, dll.) diinterpretasikan sebagai slot catatan lama dan tidak ditampilkan.
Ini efek samping dari pencabutan field remark oleh WeChat pada 2023 — dan tidak didokumentasikan secara jelas.
Perbaikannya: gunakan nama netral seperti message, info, atau desc, atau tambahkan field pengisi setelah notes.
Untuk masalah “tidak ada error tapi tidak tampil”, mengubah jumlah field, posisi, dan nama satu per satu lebih cepat daripada mencari di dokumentasi.