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.

Setup

1. Connect by QR Code (Recommended)

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.

2. Enter Credentials Manually

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).

3. Configure Mopheus

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. Verify

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 Works

Inbound: WeCom → Mopheus

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 → WeCom

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 Constraint

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 History

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.

Troubleshooting