WeChat Conta Oficial — campo «notes» da mensagem de modelo não aparece — investigação e solução

Problema

Ao enviar mensagens de modelo a partir da conta de testes (sandbox) de uma WeChat Conta Oficial, deparei-me com um comportamento estranho: o modelo define 6 campos, mas o campo notes (observação) nunca é exibido. Os outros 5 campos aparecem normalmente.

Conteúdo do modelo:

1
Nome: {{name.DATA}}
2
Telefone: {{phone.DATA}}
3
Hora: {{time.DATA}}
4
Serviço: {{services.DATA}}
5
Funcionário: {{staff.DATA}}
6
Observação: {{notes.DATA}}

A chamada à API retorna sucesso (errcode = 0), mas na mensagem recebida no WeChat só aparecem as 5 primeiras linhas — a linha da observação desaparece por inteiro, incluindo o rótulo «Observação».

Investigação

1. Descartar limite de número de campos

Primeira hipótese: a conta sandbox tem limite de 5 campos. Teste:

Remover o campo «Funcionário» e enviar apenas 5 → notes continua sem aparecer
Subir até 9 campos → todos os campos, incluindo notes, são exibidos

Conclusão: não é limite de número de campos.

2. Descartar limite de comprimento

Segundo a documentação oficial, cada linha de uma mensagem de modelo é limitada a 20 caracteres e o total a 200. Os dados de teste ficavam muito abaixo.

Conclusão: também não é problema de comprimento.

3. Identificar o padrão real

Após vários testes surge um padrão claro:

Número de campos	Posição de notes	notes visível?
6 campos	última	Não
9 campos	6.º (não último)	Sim
7 campos	6.º (não último)	Sim

Ou seja: enquanto notes for a última linha do modelo, ele desaparece. Basta haver outro campo depois para voltar a aparecer.

4. Testar o nome do campo

Mantendo notes na última posição, alteramos apenas o nome:

Nome do campo	Visível?
notes	Não
remark	Não
info	Sim
message	Sim

notes e remark somem; info e message aparecem sem problema.

Causa raiz

A API de mensagens de modelo do WeChat Conta Oficial originalmente suportava um parâmetro remark de nível superior, renderizado como uma «observação» no rodapé da mensagem. Em 30 de março de 2023, o WeChat publicou o aviso:

As mensagens de modelo deixarão de exibir o campo remark.

Essa retirada não atinge apenas o parâmetro remark de nível superior. O WeChat também faz correspondência semântica em nomes de campo como notes e remark — quando esse nome aparece como último campo do modelo, é descartado silenciosamente pelo caminho de compatibilidade com o antigo remark.

Resumindo:

notes e remark são nomes de campo reservados nas mensagens de modelo do WeChat.
Na última posição, disparam a lógica de compatibilidade do antigo remark e somem sem aviso.
Em outra posição, ou com outro nome, aparecem normalmente.

Soluções

Opção 1: renomear o campo (recomendado)

Solução mais limpa: renomear notes para um nome fora do conjunto reservado, como message, info, desc etc.

1
Nome: {{name.DATA}}
2
Telefone: {{phone.DATA}}
3
Hora: {{time.DATA}}
4
Serviço: {{services.DATA}}
5
Funcionário: {{staff.DATA}}
6
Mensagem: {{message.DATA}}

Opção 2: adicionar um campo de preenchimento após notes

Se renomear não é viável (modelo já aprovado, em produção, usado por várias integrações), adicione um campo «filler» depois de notes para que não seja mais a última linha:

1
Nome: {{name.DATA}}
2
Telefone: {{phone.DATA}}
3
Hora: {{time.DATA}}
4
Serviço: {{services.DATA}}
5
Funcionário: {{staff.DATA}}
6
Observação: {{notes.DATA}}
7
Outro: {{other.DATA}}

Ao enviar, other pode ser string vazia ou um placeholder.

Alteração de código

No backend, renomeie o campo notes para message no payload:

1
// IMPORTANTE: não use notes como nome de campo.
2
// O WeChat trata como o campo "remark" reservado e descarta silenciosamente.
3
return {
4
  name,
5
  phone,
6
  time: timeRange,
7
  services,
8
  staff,
9
  message  // antes: notes
10
};

Conclusões

As mensagens de modelo do WeChat Conta Oficial têm nomes de campo reservados. Nomes com semântica «remark» (notes, remark etc.) são interpretados como o antigo slot de observação e não são exibidos.
É efeito colateral da retirada do campo remark pelo WeChat em 2023 — e não está documentado de forma destacada.
A correção é usar um nome neutro como message, info ou desc, ou adicionar um campo de preenchimento após notes.
Para problemas do tipo «sem erro, mas sem aparecer», compensa variar número de campos, posição e nome uma variável de cada vez — encontra-se o padrão antes da documentação.