WeCom Callback (자본 앱)

Hermes to WeCom (Enterprise WeChat)을 Callback/webhook 모델을 사용하여 자체 구축 된 엔터프라이즈 응용 프로그램을 연결합니다.

WeCom Bot 대 WeCom 콜백

Hermes는 2개의 WeCom 통합 형태를 지원합니다: -WeCom Bot — bot-style, WebSocket을 통해 연결. Simpler 설정, 그룹 채팅에서 작동합니다.

• ** WeCom Callback** (이 페이지) - 자체 제작 된 응용 프로그램은 암호화 된 XML 콜백을받습니다. 사용자의 WeCom 사이드바에서 일류 앱으로 표시합니다. 다국적 라우팅 지원 주요 특징

그것이 작동하는 방법

1. WeCom 관리자 콘솔에서 자체 제작 응용 프로그램을 등록
2. WeCom는 암호화된 XML을 HTTP 콜백 엔드포인트로 밀어줍니다.
3. Hermes는 메시지를 해독하고, 에이전트을 위해 그것을 인용합니다
4. 즉시 인정 (silent - 사용자에게 표시되지 않음)
5. 에이전트은 요구 (일반적으로 3-30 분)를 가공합니다
6. 대답은 WeCom message/send API를 통해 proactively 배달됩니다

필수품

• WeCom 기업 계정 관리자 액세스
• aiohttp 및 httpx Python 패키지 (기본 설치에 포함)
• 콜백 URL에 대한 공개적으로 도달 가능한 서버 (또는 ngrok 같은 터널)

설치

##1. WeCom에서 Self-Built 앱 만들기

1. WeCom 관리자 콘솔로 이동 → 응용 프로그램 → 앱 2.Corp ID (관리자 콘솔 상단에 표시)
2. 앱 설정에서 Corp Secret를 만듭니다.
3. 앱의 개요 페이지에서 Agent ID를 참고하세요.
4. Receive Messages에서 콜백 URL을 구성합니다.

• URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
• 토큰: 임의의 토큰 생성 (WeCom은 하나 제공)
• EncodingAESKey: 키 생성 (WeCom는 하나 제공)

##2. 환경 변수 구성

.env 파일에 추가:

사이트맵

##3. 게이트웨이 시작

hermes gateway

(hermes gateway start를 hermes gateway install가 systemd/launchd 서비스를 등록한 후만 사용)

콜백 어댑터는 구성된 포트에서 HTTP 서버를 시작합니다. WeCom은 GET 요청을 통해 콜백 URL을 확인하고 POST를 통해 메시지를 전송합니다.

구성 참조

config.yaml에서 이러한 설정 platforms.wecom_callback.extra, 또는 환경 변수를 사용:

설정	기본	설명
corp_id
corp_secret
agent_id
token
encoding_aes_key	-	콜백 암호화를 위한 43-character AES 키
host	0.0.0.0	HTTP 콜백 서버의 Bind 주소
port	8645	HTTP 콜백 서버 포트
path	/wecom/callback	콜백 엔드포인트 URL 경로

멀티앱 루팅

여러 자체 내장 응용 프로그램을 실행하는 기업 (예, 다른 부서 또는 자회사에 걸쳐), apps 목록에 config.yaml를 구성:

사이트맵

사용자는 corp_id:user_id에 의해 교차로 충돌을 방지합니다. 사용자가 메시지를 보낼 때, 어댑터 레코드는 앱 (corp)에 속하고 올바른 앱의 액세스 토큰을 통해 replies를 전달합니다.

접근 제한

사용자가 앱과 상호 작용할 수 있는 제한:

사이트맵

엔드포인트

어댑터 노출:

방법	길	목적
GET	/wecom/callback	URL 인증핸드레이크(WeCom은 설치 중)
POST	/wecom/callback	암호화된 메시지 콜백 (WeCom는 사용자 메시지를 여기에 보냅니다)
GET	/health	건강 검사 - {"status": "ok"} 반환

암호화

모든 콜백 페이로드는 EncodingAESKey를 사용하여 AES-CBC로 암호화됩니다. 접합기 손잡이:

• **인바운드 **: XML 페이로드를 해독, SHA1 서명 확인
• 아웃바운드: proactive API를 통해 전송됩니다 (암호화되지 않음)

암호화 구현은 Tencent의 공식 WXBizMsgCrypt SDK와 호환됩니다.

제한

• No Streaming — replies는 에이전트가 종료한 후 완전한 메시지로 도착합니다. -No typing Indicators - 콜백 모델은 입력 상태를 지원하지 않습니다.
• Text only - 현재 입력에 대한 텍스트 메시지를 지원; image/file/voice 아직 구현되지 않았습니다. 에이전트는 WeCom 플랫폼 힌트 (이미지, 문서, 비디오, 음성)를 통해 아웃바운드 미디어 기능의 인식입니다.
• **Response latency ** - 에이전트 세션은 3-30 분 정도 걸립니다. 사용자는 완료시 응답을 참조하세요.