WeCom (Enterprise WeChat)

Python dependency commands on this page use a PM-prepared source checkout. After a dependency change, reactivate the checkout and restart Mibyan. Connect Mibyan to WeCom (企业微信), Tencent’s enterprise messaging platform. The adapter uses WeCom’s AI Bot WebSocket gateway for real-time bidirectional communication — no public endpoint or webhook needed. See also: WeCom Callback for inbound webhook setup.

Prerequisites

A WeCom organization account
An AI Bot created in the WeCom Admin Console
The Bot ID and Secret from the bot’s credentials page
Python packages: aiohttp and httpx

Setup

Step 1: Create an AI Bot

Recommended: Scan-to-Create (one command)

mibyan gateway setup

Select WeCom and scan the QR code with your WeCom mobile app. Mibyan will automatically create a bot application with the correct permissions and save the credentials. The setup wizard will:

Display a QR code in your terminal
Wait for you to scan it with the WeCom mobile app
Automatically retrieve the Bot ID and Secret
Guide you through access control configuration

Alternative: Manual Setup

If scan-to-create is not available, the wizard falls back to manual input:

Log in to the WeCom Admin Console
Navigate to Applications → Create Application → AI Bot
Configure the bot name and description
Copy the Bot ID and Secret from the credentials page
Run mibyan gateway setup, select WeCom, and enter the credentials when prompted

Keep the Bot Secret private. Anyone with it can impersonate your bot.

Step 2: Configure Mibyan

Option A: Interactive Setup (Recommended)

mibyan gateway setup

Select WeCom and follow the prompts. The wizard will guide you through:

Bot credentials (via QR scan or manual entry)
Access control settings (allowlist, pairing mode, or open access)
Home channel for notifications

Option B: Manual Configuration

Add the following to ~/.mibyan/.env:

WECOM_BOT_ID=your-bot-id
WECOM_SECRET=your-secret

# Optional: restrict access
WECOM_ALLOWED_USERS=user_id_1,user_id_2

# Optional: home channel for cron/notifications
WECOM_HOME_CHANNEL=chat_id

Step 3: Start the gateway

mibyan gateway

Features

WebSocket transport — persistent connection, no public endpoint needed
DM and group messaging — configurable access policies
Per-group sender allowlists — fine-grained control over who can interact in each group
Media support — images, files, voice, video upload and download
AES-encrypted media — automatic decryption for inbound attachments
Quote context — preserves reply threading
Markdown rendering — rich text responses
Reply correlation — responses are correlated to the inbound message context
Auto-reconnect — exponential backoff on connection drops

Streaming and typing indicatorsThe WeCom adapter streams responses natively over WeCom’s msgtype: "stream" protocol: the client shows a thinking/typing bubble as soon as a turn starts, and the reply renders token-by-token in a single bubble as the model generates it. Tool-call progress is folded into the same bubble. Native streaming follows the global streaming switch, which is off by default: turn it on with streaming.enabled: true in config.yaml. WeCom’s per-platform display.platforms.wecom.streaming (default true) only applies while the global switch is on; set it to false to keep single-shot delivery on WeCom.

Configuration Options

Set these in config.yaml under platforms.wecom.extra:

Key	Default	Description
`bot_id`	—	WeCom AI Bot ID (required)
`secret`	—	WeCom AI Bot Secret (required)
`websocket_url`	`wss://openws.work.weixin.qq.com`	WebSocket gateway URL
`dm_policy`	`open`	DM access: `open`, `allowlist`, `disabled`, `pairing`
`group_policy`	`open`	Group access: `open`, `allowlist`, `disabled`
`allow_from`	`[]`	User IDs allowed for DMs (when dm_policy=allowlist)
`group_allow_from`	`[]`	Group IDs allowed (when group_policy=allowlist)
`groups`	`{}`	Per-group configuration (see below)
`stream_keepalive_enabled`	`false`	Send periodic keepalive frames to refresh WeCom’s ~6-minute reply-stream window on long turns
`stream_keepalive_interval_seconds`	`120`	Keepalive frame cadence when enabled
`stream_safe_duration_seconds`	`330`	Stream age after which finalize prefers the reliable proactive send

Access Policies

DM Policy

Controls who can send direct messages to the bot:

Value	Behavior
`open`	Anyone can DM the bot (default)
`allowlist`	Only user IDs in `allow_from` can DM
`disabled`	All DMs are ignored
`pairing`	Pairing mode (for initial setup)

WECOM_DM_POLICY=allowlist

Group Policy

Controls which groups the bot responds in:

Value	Behavior
`open`	Bot responds in all groups (default)
`allowlist`	Bot only responds in group IDs listed in `group_allow_from`
`disabled`	All group messages are ignored

WECOM_GROUP_POLICY=allowlist

Per-Group Sender Allowlists

For fine-grained control, you can restrict which users are allowed to interact with the bot within specific groups. This is configured in config.yaml:

platforms:
  wecom:
    enabled: true
    extra:
      bot_id: "your-bot-id"
      secret: "your-secret"
      group_policy: "allowlist"
      group_allow_from:
        - "group_id_1"
        - "group_id_2"
      groups:
        group_id_1:
          allow_from:
            - "user_alice"
            - "user_bob"
        group_id_2:
          allow_from:
            - "user_charlie"
        "*":
          allow_from:
            - "user_admin"

How it works:

The group_policy and group_allow_from controls determine whether a group is allowed at all.
If a group passes the top-level check, the groups.<group_id>.allow_from list (if present) further restricts which senders within that group can interact with the bot.
A wildcard "*" group entry serves as a default for groups not explicitly listed.
Allowlist entries support the * wildcard to allow all users, and entries are case-insensitive.
Entries can optionally use the wecom:user: or wecom:group: prefix format — the prefix is stripped automatically.

If no allow_from is configured for a group, all users in that group are allowed (assuming the group itself passes the top-level policy check).

Media Support

Inbound (receiving)

The adapter receives media attachments from users and caches them locally for agent processing:

Type	How it’s handled
Images	Downloaded and cached locally. Supports both URL-based and base64-encoded images.
Files	Downloaded and cached. Filename is preserved from the original message.
Voice	Voice message text transcription is extracted if available.
Mixed messages	WeCom mixed-type messages (text + images) are parsed and all components extracted.

Quoted messages: Media from quoted (replied-to) messages is also extracted, so the agent has context about what the user is replying to.

AES-Encrypted Media Decryption

WeCom encrypts some inbound media attachments with AES-256-CBC. The adapter handles this automatically:

When an inbound media item includes an aeskey field, the adapter downloads the encrypted bytes and decrypts them using AES-256-CBC with PKCS#7 padding.
The AES key is the base64-decoded value of the aeskey field (must be exactly 32 bytes).
The IV is derived from the first 16 bytes of the key.
This requires the cryptography Python package (mibyan pm repair).

No configuration is needed — decryption happens transparently when encrypted media is received.

Outbound (sending)

Method	What it sends	Size limit
`send`	Markdown text messages	4000 chars
`send_image` / `send_image_file`	Native image messages	10 MB
`send_document`	File attachments	20 MB
`send_voice`	Voice messages (AMR format only for native voice)	2 MB
`send_video`	Video messages	10 MB

Chunked upload: Files are uploaded in 512 KB chunks through a three-step protocol (init → chunks → finish). The adapter handles this automatically. Automatic downgrade: When media exceeds the native type’s size limit but is under the absolute 20 MB file limit, it is automatically sent as a generic file attachment instead:

Images > 10 MB → sent as file
Videos > 10 MB → sent as file
Voice > 2 MB → sent as file
Non-AMR audio → sent as file (WeCom only supports AMR for native voice)

Files exceeding the absolute 20 MB limit are rejected with an informational message sent to the chat.

Reply-Mode Responses

When the bot receives a message via the WeCom callback, the adapter remembers the inbound request ID. If a response is sent while the request context is still active, the adapter uses WeCom’s reply-mode (aibot_respond_msg) to correlate the response directly to the inbound message. This provides a more natural conversation experience in the WeCom client. When a native reply stream is active, the response streams incrementally through reply-mode msgtype: "stream" frames. If the inbound request context has expired or is unavailable (or a stream frame fails), the adapter falls back to proactive message sending via aibot_send_msg. Reply-mode also works for media: uploaded media can be sent as a reply to the originating message.

Connection and Reconnection

The adapter maintains a persistent WebSocket connection to WeCom’s gateway at wss://openws.work.weixin.qq.com.

Connection Lifecycle

Connect: Opens a WebSocket connection and sends an aibot_subscribe authentication frame with the bot_id and secret.
Heartbeat: Sends application-level ping frames every 30 seconds to keep the connection alive.
Listen: Continuously reads inbound frames and dispatches message callbacks.

Reconnection Behavior

On connection loss, the adapter uses exponential backoff to reconnect:

Attempt	Delay
1st retry	2 seconds
2nd retry	5 seconds
3rd retry	10 seconds
4th retry	30 seconds
5th+ retry	60 seconds

After each successful reconnection, the backoff counter resets to zero. All pending request futures are failed on disconnect so callers don’t hang indefinitely.

Deduplication

Inbound messages are deduplicated using message IDs with a 5-minute window and a maximum cache of 1000 entries. This prevents double-processing of messages during reconnection or network hiccups.

All Environment Variables

Variable	Required	Default	Description
`WECOM_BOT_ID`	✅	—	WeCom AI Bot ID
`WECOM_SECRET`	✅	—	WeCom AI Bot Secret
`WECOM_ALLOWED_USERS`	—	(empty)	Comma-separated user IDs for the gateway-level allowlist
`WECOM_HOME_CHANNEL`	—	—	Chat ID for cron/notification output
`WECOM_WEBSOCKET_URL`	—	`wss://openws.work.weixin.qq.com`	WebSocket gateway URL
`WECOM_DM_POLICY`	—	`open`	DM access policy
`WECOM_GROUP_POLICY`	—	`open`	Group access policy

Troubleshooting

Problem	Fix
`WECOM_BOT_ID and WECOM_SECRET are required`	Set both env vars or configure in setup wizard
`WeCom startup failed: aiohttp not installed`	Install aiohttp: `python -c "import pm; pm.sync_venv(['messaging'], explicit=True)"`
`WeCom startup failed: httpx not installed`	Install httpx: `mibyan pm repair`
`invalid secret (errcode=40013)`	Verify the secret matches your bot’s credentials
`Timed out waiting for subscribe acknowledgement`	Check network connectivity to `openws.work.weixin.qq.com`
Bot doesn’t respond in groups	Check `group_policy` setting and ensure the group ID is in `group_allow_from`
Bot ignores certain users in a group	Check per-group `allow_from` lists in the `groups` config section
Media decryption fails	Install `cryptography`: `mibyan pm repair`
`cryptography is required for WeCom media decryption`	The inbound media is AES-encrypted. Install: `mibyan pm repair`
Voice messages sent as files	WeCom only supports AMR format for native voice. Other formats are auto-downgraded to file.
`File too large` error	WeCom has a 20 MB absolute limit on all file uploads. Compress or split the file.
Images sent as files	Images > 10 MB exceed the native image limit and are auto-downgraded to file attachments.
`Timeout sending message to WeCom`	The WebSocket may have disconnected. Check logs for reconnection messages.
`WeCom websocket closed during authentication`	Network issue or incorrect credentials. Verify bot_id and secret.

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

البداية

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

الميزات

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

التكاملات

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

دليل المطوّر

المرجع

WeCom (Enterprise WeChat)

Prerequisites

Setup

Step 1: Create an AI Bot

Recommended: Scan-to-Create (one command)

Alternative: Manual Setup

Step 2: Configure Mibyan

Option A: Interactive Setup (Recommended)

Option B: Manual Configuration

Step 3: Start the gateway

Features

Configuration Options

Access Policies

DM Policy

Group Policy

Per-Group Sender Allowlists

Media Support

Inbound (receiving)

AES-Encrypted Media Decryption

Outbound (sending)

Reply-Mode Responses

Connection and Reconnection

Connection Lifecycle

Reconnection Behavior

Deduplication

All Environment Variables

Troubleshooting

​Prerequisites

​Setup

​Step 1: Create an AI Bot

​Recommended: Scan-to-Create (one command)

​Alternative: Manual Setup

​Step 2: Configure Mibyan

​Option A: Interactive Setup (Recommended)

​Option B: Manual Configuration

​Step 3: Start the gateway

​Features

​Configuration Options

​Access Policies

​DM Policy

​Group Policy

​Per-Group Sender Allowlists

​Media Support

​Inbound (receiving)

​AES-Encrypted Media Decryption

​Outbound (sending)

​Reply-Mode Responses

​Connection and Reconnection

​Connection Lifecycle

​Reconnection Behavior

​Deduplication

​All Environment Variables

​Troubleshooting

Prerequisites

Setup

Step 1: Create an AI Bot

Recommended: Scan-to-Create (one command)

Alternative: Manual Setup

Step 2: Configure Mibyan

Option A: Interactive Setup (Recommended)

Option B: Manual Configuration

Step 3: Start the gateway

Features

Configuration Options

Access Policies

DM Policy

Group Policy

Per-Group Sender Allowlists

Media Support

Inbound (receiving)

AES-Encrypted Media Decryption

Outbound (sending)

Reply-Mode Responses

Connection and Reconnection

Connection Lifecycle

Reconnection Behavior

Deduplication

All Environment Variables

Troubleshooting