위챗(WeChat) 공식 계정 템플릿 메시지에서 notes 필드가 표시되지 않는 문제 분석과 해결

문제 상황

위챗(微信) 공식 계정 테스트 계정에서 템플릿 메시지를 보내던 중 이상한 문제를 만났습니다. 템플릿에 6개 필드를 정의했는데 notes(비고) 필드만 끝까지 표시되지 않고, 나머지 5개 필드는 정상적으로 표시되었습니다.

템플릿 내용은 다음과 같습니다.

1
이름: {{name.DATA}}
2
전화: {{phone.DATA}}
3
시간: {{time.DATA}}
4
항목: {{services.DATA}}
5
담당자: {{staff.DATA}}
6
비고: {{notes.DATA}}

API 호출은 성공(errcode = 0)을 반환했는데 실제 위챗에 도착한 메시지에는 5줄만 보이고 비고 줄이 통째로 사라졌습니다.

원인 추적 과정

1. 필드 개수 제한 검증

처음에는 “테스트 계정은 필드 개수 상한(최대 5개)이 있을 것”이라고 의심했습니다. 그러나 테스트 결과:

• “담당자” 필드를 제거해 5개만 보냄 → 비고는 여전히 표시되지 않음
• 필드를 9개까지 늘림 → 비고를 포함해 모든 필드가 표시됨

결론: 필드 개수 제한이 아니다.

2. 문자 수 제한 검증

위챗 공식 문서에 따르면 템플릿 메시지는 한 줄당 20자 이내, 전체 200자 이내입니다. 테스트 데이터는 이 제한과 거리가 멀었습니다.

결론: 문자 수 문제도 아니다.

3. 핵심 패턴 발견

반복 테스트로 명확한 패턴을 찾았습니다.

즉, notes가 템플릿의 마지막 줄에 있을 때만 표시가 사라집니다. 위치를 마지막에서 빼면 다시 나타납니다.

4. 필드 이름 자체 검증

notes를 마지막 줄에 둔 채 이름만 바꿔서 테스트:

notes와 remark는 모두 표시되지 않고, info, message는 정상적으로 표시됩니다.

원인 분석

위챗 공식 계정 템플릿 메시지 API에는 본래 최상위 remark 매개변수가 있었고, 메시지 하단에 별도의 “비고” 영역으로 렌더링되었습니다. 그러나 2023년 3월 30일 위챗은 다음과 같은 공지를 발표했습니다.

템플릿 메시지에서 비고(remark) 필드를 더 이상 표시하지 않는다.

이 변경은 최상위 remark 매개변수뿐 아니라 필드 이름으로 사용된 notes/remark에도 영향을 미쳤습니다. 위챗 측이 “비고” 의미를 가진 필드 이름을 내부적으로 매칭하고 있고, 그것이 템플릿의 마지막 줄에 등장할 경우 옛 remark 호환 로직을 타고 조용히 폐기되는 동작을 보입니다.

정리하면:

• notes, remark는 위챗 템플릿 메시지의 예약 필드 이름
• 마지막 줄에 두면 옛 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
// 위챗이 예약된 "비고" 필드로 인식해 표시하지 않음.
3
return {
4
  name,
5
  phone,
6
  time: timeRange,
7
  services,
8
  staff,
9
  message  // 원래는 notes
10
};

정리

1. 위챗 공식 계정 템플릿 메시지에는 예약 필드 이름이 있고, notes/remark 등 “비고” 의미의 이름은 표시되지 않는다.
2. 이는 2023년 위챗이 템플릿 메시지의 remark 표시를 폐지한 후 남은 호환 동작이며, 공식 문서에 분명히 명시되어 있지 않다.
3. 해결 방법은 message/info/desc 등 일반 이름으로 바꾸거나, 마지막 자리에 채움 필드를 추가하는 것이다.
4. “오류는 없는데 안 보인다” 류의 문제는 필드 수, 위치, 이름을 한 번에 하나씩 바꾸며 비교하는 것이 가장 빠른 디버깅 방법이다.

참고 자료

• 위챗 공식 계정 템플릿 메시지 API 문서
• 템플릿 메시지 글자 수 제한 및 remark 변경 안내