WeCom Callback Mode — Custom Apps

Think of it like setting up a dedicated office mailbox for your AI assistant—instead of having it lurk in group chats, you give it its own desk where people can walk up and leave messages directly.

What’s the Big Difference?

Hermes Agent gives you two ways to connect WeCom (Enterprise WeChat). The Bot mode is like a friendly assistant who joins group chats—quick to set up, but limited. Callback mode is different: you build a custom app that appears in your employees’ WeCom sidebar, just like any official app. It feels native, supports multiple companies, and handles encrypted messages securely.

The trade-off? You need a public server to receive messages. But don’t worry—a simple tunnel like ngrok works fine for testing.

---

How It Actually Works

Here’s the flow in plain English:

1. Someone sends a message to your custom app in WeCom.
2. WeCom encrypts that message and sends it to your server’s HTTP endpoint.
3. Hermes decrypts it, queues it for the AI agent, and immediately tells WeCom “got it” (silently—the user sees nothing yet).
4. The agent thinks for 3–30 minutes (depending on your task).
5. Hermes sends the reply back proactively using WeCom’s message API.

No polling. No delays. Just a clean, asynchronous conversation.

---

Step-by-Step Setup

1. Create the App in WeCom Admin

Log into the WeCom Admin Console, go to Applications → Create App.
Note your Corp ID (top of the console) and create a Corp Secret.
On the app’s overview page, grab the Agent ID.

Under Receive Messages, configure:

• URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
• Token: generate a random one
• EncodingAESKey: generate a 43-character key

2. Set Environment Variables

Add these to your .env file:

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_PORT = 8645
WECOM_CALLBACK_ALLOWED_USERS = user1,user2

3. Start the Gateway

hermes gateway

Note: Only use hermes gateway start after you’ve run hermes gateway install to register the service.

The callback adapter starts an HTTP server on port 8645. WeCom will verify the URL via a GET request, then start sending messages via POST.

---

Configuration Reference

You can also set these in config.yaml under platforms.wecom_callback.extra:

Setting	Default	Description
corp_id	—	Required. Your WeCom Corp ID
corp_secret	—	Required. App secret
agent_id	—	Required. Your app’s Agent ID
token	—	Required. Callback verification token
encoding_aes_key	—	Required. 43-char AES key
host	unset (dual-stack)	Bind address for HTTP server
port	8645	Port for the callback server

---

Wrapping Up

WeCom Callback mode is the “official” way to integrate Hermes into your enterprise workflow. It’s more setup than the bot, but the payoff is a polished, first-class app experience for your users.

Practical tip: Start with ngrok before exposing a real server. Run ngrok http 8645, use that URL in the WeCom console, and test with a single user. Once it works, switch to a production server and lock down WECOM_CALLBACK_ALLOWED_USERS to your team. Happy building!