WeChat OA (공众号)

48시간 응답 윈도우 내에서 WeChat 공식 계정 고객 서비스 메시지를 전송합니다. WeCom과 동일한 암호화 봉투를 사용합니다.

🟡 발신 준비 완료, 수신 지원, 48시간 윈도우. 아웃바운드 고객 서비스 메시지에는 제약이 있습니다. 사용자가 최근 48시간 이내에 공식 계정(OA)과 상호작용한 적이 있어야 합니다. 그렇지 않으면 플랫폼이 errcode 45015를 반환하고 메시지는 전송되지 않습니다. 콜드 푸시가 필요한 프로덕션 배포에서는 Template Messages（사전 승인된 템플릿）를 사용해야 하며, 이 기능은 향후 추가될 예정입니다.

제공 기능

아웃바운드 텍스트: POST /cgi-bin/message/custom/send?access_token=...를 통해 최근 48시간 이내에 공식 계정에 메시지를 보낸 openid로 전송합니다.
인바운드 메시지 이벤트: /webhooks/wechat-oa에서 수신합니다. WeCom과 동일한 SHA1 정렬 + AES-256-CBC 봉투를 사용합니다（공유 wxcrypt 헬퍼가 양쪽 모두를 처리합니다）. GET 핸드셰이크에서 작은 차이점이 하나 있습니다. WeChat OA는 4-튜플이 아닌 3-튜플 [token, timestamp, nonce]로 서명합니다.
앱별 access_token 캐싱: 2시간 동안 유지됩니다.
현재 텍스트만 지원합니다. 이미지 / 뉴스 / 템플릿 메시지는 이후 구현 예정입니다.
텍스트 최대 길이는 2048자입니다.

설정

1. 공식 계정 생성 또는 등록

WeChat 공개 플랫폼에 로그인합니다（고객 서비스 API를 사용하려면 구독 계정이 아닌 서비스 계정이 필요합니다）.
"설정" → "기본 정보"에서 AppID와 AppSecret을 확인합니다.
"설정" → "서버 구성"에서 다음을 입력합니다.
- URL: https://<your-host>/webhooks/wecom
- Token: 임의의 불투명 문자열（WECHAT_OA_TOKEN으로 사용됩니다）
- EncodingAESKey: "랜덤 생성"을 클릭합니다（43자, WECHAT_OA_AES_KEY로 사용됩니다）
- 암호화 모드: "안전 모드"（암호화）권장
"제출"을 클릭합니다. WeChat이 URL로 GET 핸드셰이크를 보내면, Minara가 복호화된 평문을 에코백합니다.

2. 기본 openid 확인

고객 서비스 API에는 openid（불투명한 사용자 식별자）가 필요합니다. 테스트 사용자가 공식 계정을 팔로우하거나 메시지를 보내거나 메뉴 항목을 클릭하는 등의 상호작용을 유도합니다. 인바운드 웹훅의 FromUserName 필드에서 openid를 확인할 수 있습니다. 해당 값을 WECHAT_OA_DEFAULT_OPENID로 저장합니다.

3. Minara 설정

minara auth messaging add
# 목록에서 `wechat_oa`를 선택합니다.

또는 환경 변수를 직접 설정합니다.

WECHAT_OA_APP_ID=wx<...>
WECHAT_OA_APP_SECRET=<opaque secret>
WECHAT_OA_TOKEN=<server config Token>
WECHAT_OA_AES_KEY=<43-char EncodingAESKey>
WECHAT_OA_DEFAULT_OPENID=<o...........>

4. 테스트

minara auth messaging test wechat_oa

주의: 기본 openid가 최근 48시간 이내에 공식 계정과 상호작용하지 않은 경우, 테스트는 errcode 45015로 실패합니다.

인바운드 웹훅

WeChat OA의 서버 구성 GET 핸드셰이크는 WeCom과 약간 다릅니다. 4-튜플 [token, ts, nonce, encrypt] 대신 3-튜플 [token, timestamp, nonce]를 사용합니다.

expected = sha1(sort([token, timestamp, nonce]).join(""))

POST 서명은 WeCom과 동일합니다. URL 쿼리의 msg_signature, 4-튜플 정렬, 본문 내부의 AES 봉투를 사용합니다.

복호화 후 내부 XML 페이로드는 Tencent의 표준 구조를 따릅니다.

<xml>
  <ToUserName>...</ToUserName>
  <FromUserName>...</FromUserName>
  <CreateTime>...</CreateTime>
  <MsgType>text</MsgType>
  <Content>...</Content>
  <MsgId>...</MsgId>
</xml>

MsgType=text 이벤트만 Agent로 전달됩니다.

제한 사항 및 주의점

48시간 고객 서비스 윈도우. 윈도우 외부에서는 모든 아웃바운드 요청이 errcode 45015를 반환합니다. 사용자 경험은 수동 응답（사용자 상호작용 후 48시간 이내）을 중심으로 설계하고, 장기 푸시에는 사전 승인된 Template Messages를 활용하시기 바랍니다.
서비스 계정 vs 구독 계정. 고객 서비스 API는 서비스 계정에서만 사용할 수 있습니다. 구독 계정은 이 프로바이더를 사용할 수 없습니다.
EncodingAESKey는 정확히 43자여야 합니다. 그렇지 않으면 부팅 중 복호화가 실패합니다.

문제 해결

"errcode 45015"

해당 openid가 최근 48시간 이내에 공식 계정과 상호작용하지 않았습니다. 이는 의도된 동작입니다. 콜드 푸시에는 Template Messages를 사용하시기 바랍니다（Minara에서는 아직 연결되지 않은 기능입니다）.

"errcode 40001 / Token invalid"

access_token 갱신에 실패했습니다. OA 콘솔에서 WECHAT_OA_APP_ID와 WECHAT_OA_APP_SECRET을 확인하시기 바랍니다.

"인바운드 웹훅이 핸드셰이크에서 401을 반환함"

3-튜플 SHA1 검사에 실패했습니다. 가장 흔한 원인은 WECHAT_OA_TOKEN의 오타입니다. OA 서버 구성 페이지의 "Token" 값과 일치하는지 확인하시기 바랍니다.

참조

환경 변수: WECHAT_OA_*
아웃바운드: apps/agent/src/messaging/wechat_oa.ts
인바운드 스펙: apps/agent/src/messaging/inbound/specs/wechat_oa.ts
고객 서비스 API: developers.weixin.qq.com / 客服消息

목차