WeCom Callback (Self-Built App)

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 bằng mô hình gọi lại/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 các cuộc trò chuyện nhóm.
• WeCom Callback (trang này) — ứng dụng tự xây dựng, nhận các lệnh gọi lại XML được mã hóa. Hiển thị dưới dạng ứng dụng hạng nhất trong thanh bên WeCom của người dùng. Hỗ trợ định tuyến đa công ty.

Nó hoạt động như thế nào

1. Bạn đăng ký ứng dụng tự xây dựng trong Bảng điều khiển dành cho quản trị viên WeCom
2. WeCom đẩy XML được mã hóa đến điểm cuối gọi lại HTTP của bạn
3. Hermes giải mã tin nhắn, xếp hàng cho đại lý
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. Nhân viên xử lý yêu cầu (thường là 3–30 phút)
6. Câu trả lời được gửi chủ động thông qua API WeCom message/send

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

• Tài khoản doanh nghiệp WeCom có quyền truy cập quản trị viên
• Gói Python aiohttp và httpx (có trong cài đặt mặc định)
• Máy chủ có thể truy cập công khai cho URL gọi lại (hoặc đường hầm như ngrok)

Thiết lập

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

1. Đi tới WeCom Admin Console → Ứng dụng → Tạo ứng dụng
2. Ghi lại ID công ty của bạn (hiển thị ở đầu bảng điều khiển dành cho quản trị viên)
3. Trong cài đặt ứng dụng, tạo Bí mật công ty
4. Lưu ý ID đại lý từ trang tổng quan của ứng dụng
5. Trong Nhận tin nhắn, hãy định cấu hình URL gọi lại: -URL: http://YOUR_PUBLIC_IP:8645/WeCom/callback
   • Mã thông báo: Tạo mã thông báo ngẫu nhiên (WeCom cung cấp một mã thông báo)
   • EncodingAESKey: Tạo khóa (WeCom cung cấp một khóa)

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

Thêm vào tệp .env của bạn:

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

# Optional
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 gọi lại khởi động máy chủ HTTP trên cổng đã định cấu hình. WeCom sẽ xác minh URL gọi lại thông qua yêu cầu GET, sau đó bắt đầu gửi tin nhắn qua POST.

Tham khảo cấu hình

Đặt những thứ này trong config.yaml trong platforms.WeCom_callback.extra hoặc sử dụng các biến môi trường:

Cài đặt	Mặc định	Mô tả
corp_id	—	ID tập đoàn doanh nghiệp WeCom (bắt buộc)
corp_secret	—	Bí mật tập đoàn cho ứng dụng tự xây dựng (bắt buộc)
agent_id	—	ID tác nhân của ứng dụng tự xây dựng (bắt buộc)
token	—	Mã thông báo xác minh gọi lại (bắt buộc)
encoding_aes_key	—	Khóa AES gồm 43 ký tự để mã hóa gọi lại (bắt buộc)
host	0.0.0.0	Địa chỉ liên kết cho máy chủ gọi lại HTTP
port	8645	Cổng cho máy chủ gọi lại HTTP
path	/WeCom/callback	Đường dẫn URL cho điểm cuối gọi lại

Định tuyến nhiều ứng dụng

Đối với các doanh nghiệp chạy nhiều ứng dụng tự xây dựng (ví dụ: giữa các phòng ban hoặc công ty con khác nhau), hãy định 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 xác định phạm vi của corp_id:user_id để ngăn chặn xung đột giữa các công ty. Khi người dùng gửi tin nhắn, bộ điều hợp sẽ ghi lại ứng dụng (tập đoàn) mà họ thuộc về và định tuyến các câu trả lời thông qua mã thông báo truy cập của ứng dụng chính xác.

Kiểm soát truy cập

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

# Allowlist specific users
WeCom_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# Or allow all users
WeCom_CALLBACK_ALLOW_ALL_USERS=true

Điểm cuối

Bộ chuyển đổi hiển thị:

Phương pháp	Đường dẫn	Mục đích
NHẬN	/WeCom/callback	Bắt tay xác minh URL (WeCom gửi thông tin này trong quá trình thiết lập)
ĐĂNG	/WeCom/callback	Gọi lại tin nhắn được mã hóa (WeCom gửi tin nhắn của người dùng tại đây)
NHẬN	/health	Kiểm tra sức khỏe — trả về {"status": "ok"}

Mã hóa

Tất cả tải trọng gọi lại đều được mã hóa bằng AES-CBC bằng EncodingAESKey. Bộ điều hợp xử lý:

• Inbound: Giải mã tải trọng XML, xác minh chữ ký SHA1
• Outbound: Phản hồi được gửi qua API chủ động (phản hồi gọi lại không được mã hóa)

Việc triển khai tiền điện tử tương thích với SDK WXBizMsgCrypt chính thức của Tencent.

Hạn chế

• Không phát trực tuyến — các câu trả lời sẽ đến dưới dạng tin nhắn hoàn chỉnh sau khi tổng đài viên kết thúc
• Không có chỉ báo nhập — mô hình gọi lại không hỗ trợ trạng thái nhập
• Chỉ văn bản — hiện hỗ trợ tin nhắn văn bản; hình ảnh/tập tin/giọng nói chưa được triển khai
• Độ trễ phản hồi — phiên của tổng đài viên mất 3–30 phút; người dùng nhìn thấy câu trả lời khi quá trình xử lý hoàn tất