Chế độ Callback của WeCom — Ứng dụng Tùy chỉnh

Hãy hình dung việc này giống như việc thiết lập một hộp thư văn phòng riêng cho trợ lý AI của bạn—thay vì để nó ẩn mình trong các cuộc trò chuyện nhóm, bạn cấp cho nó một chiếc bàn riêng, nơi mọi người có thể đến và để lại tin nhắn trực tiếp.

Điểm Khác Biệt Lớn Là Gì?

Hermes Agent cung cấp cho bạn hai cách để kết nối WeCom (WeChat Doanh Nghiệp). Chế độ Bot giống như một trợ lý thân thiện tham gia vào các cuộc trò chuyện nhóm—thiết lập nhanh chóng, nhưng bị giới hạn. Chế độ callback thì khác: bạn xây dựng một ứng dụng tùy chỉnh xuất hiện trong thanh bên WeCom của nhân viên, giống như bất kỳ ứng dụng chính thức nào. Nó mang lại cảm giác tự nhiên, hỗ trợ nhiều công ty và xử lý các tin nhắn được mã hóa một cách an toàn.

Cái giá phải trả? Bạn cần một máy chủ công khai để nhận tin nhắn. Nhưng đừng lo—một đường hầm đơn giản như ngrok là đủ dùng để thử nghiệm.

Cách Thức Hoạt Động Thực Sự

Đây là luồng hoạt động được giải thích một cách dễ hiểu:

Ai đó gửi tin nhắn đến ứng dụng tùy chỉnh của bạn trong WeCom.
WeCom mã hóa tin nhắn đó và gửi đến endpoint HTTP trên máy chủ của bạn.
Hermes giải mã, đưa vào hàng đợi cho tác nhân AI, và ngay lập tức báo cho WeCom là “đã nhận” (một cách âm thầm—người dùng chưa thấy gì cả).
Tác nhân suy nghĩ từ 3–30 phút (tùy thuộc vào nhiệm vụ của bạn).
Hermes chủ động gửi phản hồi lại bằng API tin nhắn của WeCom.

Không cần hỏi vòng (polling). Không trễ. Chỉ là một cuộc trò chuyện không đồng bộ, rõ ràng.

Hướng Dẫn Thiết Lập Từng Bước

1. Tạo Ứng Dụng Trong Bảng Quản Trị WeCom

Đăng nhập vào Bảng Quản Trị WeCom, đi tới Ứng Dụng → Tạo Ứng Dụng.
Ghi chú Corp ID của bạn (ở đầu bảng điều khiển) và tạo một Corp Secret.
Trên trang tổng quan của ứng dụng, lấy Agent ID.

Trong phần Nhận Tin Nhắn, cấu hình:

URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
Token: tạo một token ngẫu nhiên
EncodingAESKey: tạo một khóa gồm 43 ký tự

2. Thiết Lập Các Biến Môi Trường

Thêm các biến này 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

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

3. Khởi Động Cổng Kết Nối

hermes gateway

Lưu ý: Chỉ sử dụng hermes gateway start sau khi bạn đã chạy hermes gateway install để đăng ký dịch vụ.

Bộ chuyển đổi callback khởi động một máy chủ HTTP trên cổng 8645. WeCom sẽ xác minh URL qua một yêu cầu GET, sau đó bắt đầu gửi tin nhắn qua POST.

Tham Chiếu Cấu Hình

Bạn cũng có thể đặt các cấu hình này trong config.yaml dưới mục platforms.wecom_callback.extra:

Cài đặt	Mặc định	Mô tả
`corp_id`	—	Bắt buộc. Corp ID WeCom của bạn
`corp_secret`	—	Bắt buộc. Bí mật ứng dụng
`agent_id`	—	Bắt buộc. Agent ID của ứng dụng bạn
`token`	—	Bắt buộc. Token xác minh callback
`encoding_aes_key`	—	Bắt buộc. Khóa AES gồm 43 ký tự
`host`	không đặt (dual-stack)	Địa chỉ liên kết cho máy chủ HTTP
`port`	8645	Cổng cho máy chủ callback

Tổng Kết

Chế độ Callback của WeCom là cách “chính thống” để tích hợp Hermes vào quy trình làm việc doanh nghiệp của bạn. Việc thiết lập phức tạp hơn so với bot, nhưng phần thưởng là một trải nghiệm ứng dụng hoàn chỉnh, đẳng cấp cho người dùng của bạn.

Mẹo thực tế: Bắt đầu với ngrok trước khi phơi bày một máy chủ thật. Chạy ngrok http 8645, sử dụng URL đó trong bảng điều khiển WeCom và thử nghiệm với một người dùng duy nhất. Khi nó hoạt động, hãy chuyển sang máy chủ sản xuất và khóa WECOM_CALLBACK_ALLOWED_USERS cho nhóm của bạn. Chúc bạn xây dựng thành công!