WeCom Callback (Self-Built App)

Connect Mibyan to WeCom (Enterprise WeChat) as a self-built enterprise application using the callback/webhook model.

WeCom Bot vs WeCom CallbackMibyan supports two WeCom integration modes:

WeCom Bot — bot-style, connects via WebSocket. Simpler setup, works in group chats.
WeCom Callback (this page) — self-built app, receives encrypted XML callbacks. Shows as a first-class app in users’ WeCom sidebar. Supports multi-corp routing.

See also: WeCom Bot for the bot-style integration.

Run mibyan gateway setup and pick WeCom Callback for a guided walk-through.

How It Works

You register a self-built application in the WeCom Admin Console
WeCom pushes encrypted XML to your HTTP callback endpoint
Mibyan decrypts the message, queues it for the agent
Immediately acknowledges (silent — nothing displayed to the user)
The agent processes the request (typically 3–30 minutes)
The reply is delivered proactively via the WeCom message/send API

Prerequisites

A WeCom enterprise account with admin access
aiohttp and httpx Python packages (included in the default install)
A publicly reachable server for the callback URL (or a tunnel like ngrok)

Setup

1. Create a Self-Built App in WeCom

Go to WeCom Admin Console → Applications → Create App
Note your Corp ID (shown at the top of the admin console)
In the app settings, create a Corp Secret
Note the Agent ID from the app’s overview page
Under Receive Messages, configure the callback URL:
- URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
- Token: Generate a random token (WeCom provides one)
- EncodingAESKey: Generate a key (WeCom provides one)

2. Configure Environment Variables

Add 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_HOST=  # optional pin; unset = dual-stack (all interfaces, IPv4+IPv6)
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2

3. Start the Gateway

mibyan gateway

(Use mibyan gateway start only after mibyan gateway install has registered the systemd/launchd service.) The callback adapter starts an HTTP server on the configured port. WeCom will verify the callback URL via a GET request, then begin sending messages via POST.

Configuration Reference

Set these in config.yaml under platforms.wecom_callback.extra, or use environment variables:

Setting	Default	Description
`corp_id`	—	WeCom enterprise Corp ID (required)
`corp_secret`	—	Corp secret for the self-built app (required)
`agent_id`	—	Agent ID of the self-built app (required)
`token`	—	Callback verification token (required)
`encoding_aes_key`	—	43-character AES key for callback encryption (required)
`host`	unset (dual-stack: all interfaces, IPv4+IPv6)	Bind address for the HTTP callback server
`port`	`8645`	Port for the HTTP callback server
`path`	`/wecom/callback`	URL path for the callback endpoint

Multi-App Routing

For enterprises running multiple self-built apps (e.g., across different departments or subsidiaries), configure the apps list in 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..."

Users are scoped by corp_id:user_id to prevent cross-corp collisions. When a user sends a message, the adapter records which app (corp) they belong to and routes replies through the correct app’s access token.

Access Control

Restrict which users can interact with the app:

# Allowlist specific users
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# Or allow all users
WECOM_CALLBACK_ALLOW_ALL_USERS=true

Endpoints

The adapter exposes:

Method	Path	Purpose
GET	`/wecom/callback`	URL verification handshake (WeCom sends this during setup)
POST	`/wecom/callback`	Encrypted message callback (WeCom sends user messages here)
GET	`/health`	Health check — returns `{"status": "ok"}`

Encryption

All callback payloads are encrypted with AES-CBC using the EncodingAESKey. The adapter handles:

Inbound: Decrypt XML payload, verify SHA1 signature
Outbound: Replies sent via proactive API (not encrypted callback response)

The crypto implementation is compatible with Tencent’s official WXBizMsgCrypt SDK.

Limitations

No streaming — replies arrive as complete messages after the agent finishes
No typing indicators — the callback model doesn’t support typing status
Text only — currently supports text messages for input; image/file/voice input not yet implemented. The agent is aware of outbound media capabilities via the WeCom platform hint (images, documents, video, voice).
Response latency — agent sessions take 3–30 minutes; users see the reply when processing completes

Troubleshooting

Signature verification failing. WeCom signs every request with the Token you registered in the admin console. A mismatch between the token configured in Mibyan and the token the admin console expects is the most common cause. Re-copy both the Token and EncodingAESKey from the admin console — they’re easy to truncate. Whitespace in ~/.mibyan/.env values around = will also break signature checks. After fixing, restart mibyan gateway run. Callback URL not reachable / verification step fails. WeCom hits the public URL you registered. Confirm:

Your reverse proxy / tunnel forwards /wecom/callback to the gateway’s port.
The URL in the admin console is HTTPS (WeCom rejects plain HTTP).
From outside your network, curl -i https://<your-domain>/wecom/callback returns something other than a timeout (a 4xx without query params is fine — it just means the listener is reachable).

Port not reachable / listener not bound. Check mibyan gateway run logs for the bound host/port. If the adapter bound to 127.0.0.1 you must front it with a reverse proxy or tunnel — WeCom’s servers can’t reach loopback. Leave extra.host unset so the default dual-stack bind (all interfaces, IPv4+IPv6) applies, or pin an interface in config.yaml (plus allowed_source_cidrs if exposing directly) or keep loopback and use a tunnel such as Cloudflare Tunnel / nginx.

تطبيق ديسكتوب

البداية

استخدام مبيان

الميزات

منصات المراسلة

التكاملات

الأدلة والدروس

دليل المطوّر

المرجع

WeCom Callback (Self-Built App)

How It Works

Prerequisites

Setup

1. Create a Self-Built App in WeCom

2. Configure Environment Variables

3. Start the Gateway

Configuration Reference

Multi-App Routing

Access Control

Endpoints

Encryption

Limitations

Troubleshooting

​How It Works

​Prerequisites

​Setup

​1. Create a Self-Built App in WeCom

​2. Configure Environment Variables

​3. Start the Gateway

​Configuration Reference

​Multi-App Routing

​Access Control

​Endpoints

​Encryption

​Limitations

​Troubleshooting

How It Works

Prerequisites

Setup

1. Create a Self-Built App in WeCom

2. Configure Environment Variables

3. Start the Gateway

Configuration Reference

Multi-App Routing

Access Control

Endpoints

Encryption

Limitations

Troubleshooting