WeCom Integration

The WeCom integration connects a WeCom smart-bot (aibot) to Mopheus via a WebSocket long-connection. Once configured, agents respond to WeCom messages in real time, and ticket status changes and comments are pushed back to the originating WeCom chat.

Connection Method ComparisonCopy Anchor Link

The group-bot, multi-group, and smart-bot capabilities above describe WeCom. Mopheus support is listed in the final row. The one-hour URL callback limit is the validity period of response_url; it does not mean the bot must keep replying for one hour.

SetupCopy Anchor Link

1. Smart Bot SetupCopy Anchor Link

Connect by QR Code (Recommended)Copy Anchor Link

1. In Mopheus, open an agent or team detail page → Integrations → Connect WeCom Bot.
2. Select Connect by QR Code, scan the displayed QR code in WeCom, then finish creation and authorization in WeCom.
3. Once the scan succeeds, Mopheus receives the Bot ID and Secret server-side and stores them encrypted for the selected agent or team. Credentials are never returned to the browser.

The installation entry requires the current member to have the channel:bind permission. Installing a bot for another agent or a team also follows the workspace ownership rule.

Enter Credentials ManuallyCopy Anchor Link

1. Go to the WeCom Admin Console → Application Management → Smart Bot.
2. Create a new smart bot. Note the Bot ID and Secret shown once at creation.
3. In Mopheus, open an agent or team detail page → Integrations → Connect WeCom Bot, then select Enter Credentials Manually.
4. Fill in the Bot ID and Secret. Optionally set a custom WebSocket URL (defaults to wss://openws.work.weixin.qq.com).

2. Self-built App (Callback Mode)Copy Anchor Link

1. In the WeCom Admin Console, open Application Management and create an app. Open its details and note the AgentId and Secret.
2. In Mopheus, open an agent or team detail page → Integrations → Connect WeCom Bot, then select Self-built App. Find the Corp ID at the bottom of My Enterprise in the WeCom Admin Console, then enter the Corp ID, Agent ID, and app Secret. Mopheus securely generates the callback Token and EncodingAESKey and stores them encrypted.
3. After creating the integration, copy the displayed callback URL, Token, and EncodingAESKey. Return to the app details in WeCom, open Receive Messages, select Set API Receive, enter the copied values, and save. The callback URL is generated from the deployment's APP_URL and the fixed path /wecom/callback/{installationId}; Next.js forwards requests to the Go API, so the public Web domain must be reachable and NEXT_PUBLIC_API_URL must point to the backend.
4. WeCom API Base URL defaults to https://qyapi.weixin.qq.com. Set the API base URL for a private deployment when needed. Mopheus obtains an access token with GET /cgi-bin/gettoken?corpid=<CorpID>&corpsecret=<Secret>, then sends messages with POST /cgi-bin/message/send?access_token=<access_token>.

Self-built app outbound messages use WeCom's Markdown message type. Content retains the existing 20 KB overall channel limit; within that limit, content over 2048 bytes is split into multiple messages at UTF-8-safe boundaries, preferring line breaks. WeCom renders only a subset of Markdown syntax.

Inbound image, file, and video callbacks download their MediaId through the configured API base URL and attach the stored file to the channel message. Outbound sends to the same member are paced at least four seconds apart (900/hour maximum); WeCom 45009 rate-limit responses are retried by the outbound queue. The account-wide daily allowance depends on the enterprise's member-cap tier (cap × 200) and is not currently known to Mopheus, so configure the app's allowed send scope conservatively in WeCom.

This mode reads the member UserID from callback XML FromUserName and reuses Mopheus's existing WeCom identity binding and channel engine. The app Secret, callback Token, and EncodingAESKey are encrypted at rest.

3. Configure MopheusCopy Anchor Link

In Admin → System Config, set:

After bot credentials are configured, do not edit the WeCom secret key through the generic config editor. Generate in System Config rotates the key and re-encrypts every existing WeCom binding in one transaction.

Before verifying the integration, configure the bot's visibility or available members and departments in the WeCom Admin Console. Connecting the bot does not automatically authorize every WeCom user. A sender outside the bot's available range may be rejected by WeCom before Mopheus receives the message.

4. VerifyCopy Anchor Link

Send any message to the bot in WeCom. On the first message, each WeCom sender receives a one-time Mopheus account binding link. Sign in and confirm the binding, then send the message again. The message is routed to the assigned agent, and the agent's reply is pushed back to the WeCom chat automatically.

The binding is per WeCom sender and per bot installation. The person who connected the bot must also complete this step when they first use the bot; WeCom does not provide Mopheus with the installer's WeCom user identity during installation.

WeCom bot availability and Mopheus account binding are separate requirements: each sender must be within the bot's available range and must complete the one-time Mopheus binding flow.

The integration section identifies the Mopheus workspace member who installed each bot binding.

How It WorksCopy Anchor Link

Inbound: WeCom → MopheusCopy Anchor Link

WeCom user sends message to smart-bot
        │
        ▼
aibot_msg_callback over WebSocket
        │
        ▼
Mopheus channel engine receives and routes message
        │
        ▼
Session created → agent task enqueued
        │
        ▼
Agent runs, produces reply
        │
        ▼
Patcher sends reply back to WeCom chat via aibot_send_msg

Outbound: Mopheus → WeComCopy Anchor Link

The Patcher component handles all outbound traffic via the shared WebSocket connection.

All outbound messages are sent as msgtype: markdown. Plain text renders correctly through the markdown path. Messages are rune-safe truncated to 4000 bytes.

Multi-Replica ConstraintCopy Anchor Link

The WeCom bot allows a single live WebSocket subscriber per bot. Mopheus enforces single-replica via the channel supervisor lease. If you scale Mopheus horizontally, set up Redis Streams relay (separate feature) before enabling the WeCom integration.

Message HistoryCopy Anchor Link

The smart-bot long connection receives only real-time events delivered to the bot. This integration does not pull ordinary group-chat history. WeCom conversation-content archiving is a separate compliance capability and is not part of smart-bot connection setup.

TroubleshootingCopy Anchor Link