WeCom Callback (Ứng dụng tự xây dựng)

Kết nối Hermes với WeCom (Enterprise WeChat) dưới dạng ứng dụng doanh nghiệp tự xây dựng sử dụng mô hình callback/webhook.

WeCom Bot vs WeCom Callback

Hermes hỗ trợ hai chế độ tích hợp WeCom:

• WeCom Bot — kiểu bot, kết nối qua WebSocket. Thiết lập đơn giản hơn, hoạt động trong chat nhóm.
• WeCom Callback (trang này) — ứng dụng tự xây dựng, nhận callback XML được mã hóa. Hiển thị như ứng dụng chính thức trong thanh bên WeCom của người dùng. Hỗ trợ định tuyến đa doanh nghiệp.

Cách hoạt động

1. Bạn đăng ký ứng dụng tự xây dựng trong Bảng quản trị WeCom
2. WeCom đẩy XML được mã hóa đến endpoint HTTP callback của bạn
3. Hermes giải mã tin nhắn, đưa vào hàng đợi cho agent
4. Xác nhận ngay lập tức (im lặng — không hiển thị gì cho người dùng)
5. Agent xử lý yêu cầu (thường 3–30 phút)
6. Phản hồi được gửi chủ động qua API message/send của WeCom

Điều kiện tiên quyết

• Tài khoản doanh nghiệp WeCom với quyền admin
• Package Python aiohttp và httpx (đã bao gồm trong bản cài đặt mặc định)
• Máy chủ có thể truy cập công khai cho URL callback (hoặc tunnel như ngrok)

Thiết lập

1. Tạo ứng dụng tự xây dựng trong WeCom

1. Truy cập Bảng quản trị WeCom → Ứng dụng → Tạo ứng dụng
2. Ghi lại Corp ID (hiển thị ở đầu bảng quản trị)
3. Trong cài đặt ứng dụng, tạo Corp Secret
4. Ghi lại Agent ID từ trang tổng quan ứng dụng
5. Trong Nhận tin nhắn, cấu hình URL callback:
   • URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
   • Token: Tạo token ngẫu nhiên (WeCom cung cấp)
   • EncodingAESKey: Tạo key (WeCom cung cấp)

2. Cấu hình biến môi trường

Thêm vào file .env:

WECOM_CALLBACK_CORP_ID=your-corp-id
WECOM_CALLBACK_CORP_SECRET=your-corp-secret
WECOM_CALLBACK_AGENT_ID=1000002
WECOM_CALLBACK_TOKEN=your-callback-token
WECOM_CALLBACK_ENCODING_AES_KEY=your-43-char-aes-key

# Tùy chọn
WECOM_CALLBACK_HOST=0.0.0.0
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2

3. Khởi động Gateway

hermes gateway start

Bộ điều hợp callback khởi động máy chủ HTTP trên cổng đã cấu hình. WeCom sẽ xác minh URL callback qua request GET, sau đó bắt đầu gửi tin nhắn qua POST.

Tham chiếu cấu hình

Đặt các giá trị này trong config.yaml dưới platforms.wecom_callback.extra, hoặc sử dụng biến môi trường:

Cài đặt	Mặc định	Mô tả
corp_id	—	Corp ID doanh nghiệp WeCom (bắt buộc)
corp_secret	—	Corp secret cho ứng dụng tự xây dựng (bắt buộc)
agent_id	—	Agent ID của ứng dụng tự xây dựng (bắt buộc)
token	—	Token xác minh callback (bắt buộc)
encoding_aes_key	—	Key AES 43 ký tự cho mã hóa callback (bắt buộc)
host	0.0.0.0	Địa chỉ bind cho máy chủ HTTP callback
port	8645	Cổng cho máy chủ HTTP callback
path	/wecom/callback	Đường dẫn URL cho endpoint callback

Định tuyến đa ứng dụng

Cho doanh nghiệp chạy nhiều ứng dụng tự xây dựng (ví dụ qua các phòng ban hoặc công ty con khác nhau), cấu hình danh sách apps trong config.yaml:

platforms:
  wecom_callback:
    enabled: true
    extra:
      host: "0.0.0.0"
      port: 8645
      apps:
        - name: "dept-a"
          corp_id: "ww_corp_a"
          corp_secret: "secret-a"
          agent_id: "1000002"
          token: "token-a"
          encoding_aes_key: "key-a-43-chars..."
        - name: "dept-b"
          corp_id: "ww_corp_b"
          corp_secret: "secret-b"
          agent_id: "1000003"
          token: "token-b"
          encoding_aes_key: "key-b-43-chars..."

Người dùng được phân tách theo corp_id:user_id để tránh xung đột giữa các doanh nghiệp. Khi người dùng gửi tin nhắn, bộ điều hợp ghi lại ứng dụng (doanh nghiệp) mà họ thuộc về và định tuyến phản hồi qua access token của ứng dụng đúng.

Kiểm soát truy cập

Giới hạn người dùng nào có thể tương tác với ứng dụng:

# Danh sách cho phép người dùng cụ thể
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# Hoặc cho phép tất cả người dùng
WECOM_CALLBACK_ALLOW_ALL_USERS=true

Endpoint

Bộ điều hợp cung cấp:

Phương thức	Đường dẫn	Mục đích
GET	/wecom/callback	Xác minh URL (WeCom gửi trong quá trình thiết lập)
POST	/wecom/callback	Callback tin nhắn mã hóa (WeCom gửi tin nhắn người dùng tại đây)
GET	/health	Kiểm tra sức khỏe — trả về {"status": "ok"}

Mã hóa

Tất cả payload callback được mã hóa bằng AES-CBC sử dụng EncodingAESKey. Bộ điều hợp xử lý:

• Đến: Giải mã payload XML, xác minh chữ ký SHA1
• Đi: Phản hồi gửi qua API chủ động (không phải phản hồi callback mã hóa)

Triển khai mã hóa tương thích với SDK WXBizMsgCrypt chính thức của Tencent.

Hạn chế

• Không streaming — phản hồi đến dưới dạng tin nhắn hoàn chỉnh sau khi agent xử lý xong
• Không có chỉ báo đang gõ — mô hình callback không hỗ trợ trạng thái đang gõ
• Chỉ văn bản — hiện tại hỗ trợ tin nhắn văn bản cho đầu vào; đầu vào hình ảnh/file/giọng nói chưa được triển khai. Agent nhận biết khả năng media đầu ra qua gợi ý nền tảng WeCom (hình ảnh, tài liệu, video, giọng nói).
• Độ trễ phản hồi — phiên agent mất 3–30 phút; người dùng thấy phản hồi khi xử lý hoàn tất