WeCom Channel - PicoClaw

WeCom (企业微信, Enterprise WeChat) is Tencent’s enterprise communication platform. PicoClaw supports three integration modes: WeCom Bot, WeCom App, and WeCom AI Bot.

Integration Modes

Choose the mode that best fits your needs:

Mode	Setup Difficulty	Features	Use Case
WeCom Bot	Easy	Group chat webhooks	Quick group bot setup
WeCom App	Medium	Custom app, private chat, proactive messaging	Full-featured enterprise integration
WeCom AI Bot	Medium	Official AI bot, streaming replies, group & private	Production-ready AI assistant

All WeCom webhook-based integrations use the shared Gateway server on port 18790 (configurable via gateway.host and gateway.port).

Mode 1: WeCom Bot (Group Webhook)

Simplest setup for group chat integration.

Prerequisites

WeCom account with group admin access
~5 minutes for setup

Setup Instructions

Create a Group Bot

Open WeCom desktop or mobile app
Go to a group chat
Tap Group Settings → Group Bots → Add Bot
Name your bot (e.g., “PicoClaw Assistant”)
Copy the Webhook URL (format: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx)

Each group needs its own bot. The webhook URL is specific to that group.

Get Token and AES Key

WeCom bots require verification:

In WeCom Admin Console → App Management → Group Bots
Find your bot and configure Receive Messages
Copy the Token and EncodingAESKey

If you don’t need to receive messages (only send), you can skip this step. However, for interactive bots, you need both credentials.

Configure PicoClaw

Edit ~/.picoclaw/config.json:

{
  "gateway": {
    "host": "127.0.0.1",
    "port": 18790
  },
  "channels": {
    "wecom": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
      "webhook_path": "/webhook/wecom",
      "allow_from": []
    }
  }
}

The webhook_path is where PicoClaw receives messages from WeCom. You need to configure this URL in WeCom Admin Console.

Set Up Webhook URL in WeCom

Go to WeCom Admin Console → Group Bot settings
Set Receive Message URL to: http://your-server:18790/webhook/wecom
Use HTTPS with reverse proxy for production

For testing, use ngrok: ngrok http 18790 and use the HTTPS URL.

Start Gateway

Run PicoClaw:

picoclaw gateway

You should see:

[INFO] gateway: Starting HTTP server on 127.0.0.1:18790
[INFO] wecom: WeCom channel initialized

Test in Group

Send a message in the group chat with the bot
The bot should respond with AI-generated replies

WeCom Bot Configuration

{
  "channels": {
    "wecom": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx",
      "webhook_path": "/webhook/wecom",
      "allow_from": []
    }
  }
}

Mode 2: WeCom App (Custom Application)

Full-featured integration with custom app capabilities.

Prerequisites

WeCom admin account
~20 minutes for setup

Setup Instructions

Create a WeCom App

Go to WeCom Admin Console
Navigate to App Management → Create App
Fill in:
- App name
- Logo
- Description
Submit and wait for approval

Get App Credentials

After approval:

Go to My Company page, copy CorpID
Open your app, copy AgentId
Copy Secret

Keep CorpID, AgentId, and Secret secure! They grant full access to your app.

Configure Receive Messages

In app settings:

Click Receive Messages → Set API
Set URL to: http://your-server:18790/webhook/wecom-app
Generate Token
Generate EncodingAESKey (click “Random Generate”)
Click Save

Configure PicoClaw

Edit ~/.picoclaw/config.json:

{
  "channels": {
    "wecom_app": {
      "enabled": true,
      "corp_id": "wwxxxxxxxxxxxxxxxx",
      "corp_secret": "YOUR_CORP_SECRET",
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-app",
      "allow_from": []
    }
  }
}

Field	Description
`corp_id`	Your organization’s CorpID
`corp_secret`	App’s Secret
`agent_id`	App’s AgentId (numeric)
`token`	Token for message verification
`encoding_aes_key`	43-character AES key
`webhook_path`	Webhook endpoint path

Start Gateway

picoclaw gateway

Verify connection in logs:

[INFO] wecom_app: WeCom App initialized
[INFO] wecom_app: AgentId: 1000002

Test the App

Open WeCom
Go to Workbench → Find your app
Send a message
Bot should respond

WeCom App Configuration

{
  "channels": {
    "wecom_app": {
      "enabled": true,
      "corp_id": "wwxxxxxxxxxxxxxxxx",
      "corp_secret": "YOUR_CORP_SECRET",
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-app",
      "allow_from": []
    }
  }
}

Mode 3: WeCom AI Bot (Official AI Integration)

Official AI bot with streaming support and advanced features.

Why AI Bot Mode?

Streaming replies: Real-time response streaming
No timeout issues: Uses streaming pull protocol
Group & private chat: Supports both
Official integration: Built for AI assistants

Prerequisites

WeCom admin account
AI Bot feature enabled (may require WeCom Pro plan)
~20 minutes for setup

Setup Instructions

Create an AI Bot

Go to WeCom Admin Console → App Management → AI Bot
Click Create AI Bot
Fill in:
- Bot name
- Description
- Avatar
Submit for approval

Configure Callback URL

After approval:

In AI Bot settings, find Callback Configuration
Set URL to: http://your-server:18790/webhook/wecom-aibot
Copy Token
Click Random Generate for EncodingAESKey
Copy the 43-character key
Click Save

WeCom AI Bot requires HTTPS for production. Use a reverse proxy or deploy on a server with SSL.

Configure PicoClaw

Edit ~/.picoclaw/config.json:

{
  "channels": {
    "wecom_aibot": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
      "welcome_message": "Hello! How can I help you?"
    }
  }
}

Field	Description
`token`	Token from AI Bot configuration
`encoding_aes_key`	43-character AES key
`webhook_path`	Webhook endpoint (default: `/webhook/wecom-aibot`)
`allow_from`	Allowed user IDs (empty = allow all)
`welcome_message`	First message users see (optional)

Start Gateway

picoclaw gateway

Look for:

[INFO] wecom_aibot: WeCom AI Bot initialized
[INFO] wecom_aibot: Streaming support enabled

Test the AI Bot

Add the AI Bot in WeCom
Send a message
Observe streaming replies (if supported by your LLM)

WeCom AI Bot Configuration

{
  "channels": {
    "wecom_aibot": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
      "welcome_message": "Hello! I'm your AI assistant. Ask me anything!"
    }
  }
}

Streaming Protocol

WeCom AI Bot Advantages:

Uses streaming pull protocol (no reply timeout)
Long tasks (>30 seconds) automatically switch to response_url push delivery
Real-time response streaming for better UX
Official AI bot support from WeCom

Access Control

All modes support allow_from to restrict access: Allow specific users:

{
  "allow_from": ["user_id_1", "user_id_2"]
}

Allow everyone:

{
  "allow_from": []
}

Finding user IDs:

Check Gateway logs when users send messages
Use WeCom Admin API to query user list
Inspect webhook payload structure

Comparison Table

Feature	WeCom Bot	WeCom App	WeCom AI Bot
Setup Difficulty	Easy	Medium	Medium
Group Chat	✅ Yes	❌ No	✅ Yes
Private Chat	❌ No	✅ Yes	✅ Yes
Proactive Messaging	❌ No	✅ Yes	✅ Yes
Streaming Replies	❌ No	❌ No	✅ Yes
Timeout Issues	⚠️ Possible	⚠️ Possible	✅ No timeout
Webhook Required	✅ Yes	✅ Yes	✅ Yes
Best For	Quick group bot	Full enterprise integration	Production AI assistant

Troubleshooting

”Signature verification failed”

Cause: Token or EncodingAESKey mismatch Solution:

Verify token and encoding_aes_key in config match WeCom Admin Console
Check for extra spaces when copying
Regenerate credentials if needed
Restart gateway

”Invalid CorpID”

Cause: Wrong CorpID or missing Solution:

Go to WeCom Admin Console → My Company
Copy CorpID exactly (starts with ww)
Update config
Restart gateway

Bot doesn’t respond

Check:

Gateway running: picoclaw gateway
Webhook URL configured in WeCom
HTTPS enabled (production requirement)
allow_from permits the user
LLM configured: picoclaw agent -m "test"

Webhook not receiving messages

Possible causes:

Webhook URL incorrect
Gateway not accessible from internet
Firewall blocking port 18790
HTTPS certificate invalid

Check:

Test webhook URL with curl
Verify Gateway logs for incoming requests
Use ngrok for testing: ngrok http 18790
Ensure gateway.host is 0.0.0.0 for external access

”App not found” errors

Cause: AgentId incorrect or app not approved Solution:

Verify AgentId in WeCom Admin Console
Check app approval status
Ensure AgentId is numeric (not string)

Privacy & Security

Security Best Practices:

Never share CorpID, Secret, Token, or EncodingAESKey
Use HTTPS for production webhooks
Never commit credentials to repositories
Use allow_from for sensitive bots
Regenerate credentials if compromised
Monitor bot usage in WeCom Admin Console
Follow your organization’s security policies

Data Privacy

WeCom integrations can access:

Messages sent to the bot
User information (name, ID, department)
Organizational structure
Group information

Be aware of:

WeCom/Tencent privacy policies
Chinese data protection regulations
Your organization’s data policies
Local data storage in PicoClaw workspace
LLM provider data logging

Complete Example

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "glm-4"
    }
  },
  "model_list": [
    {
      "model_name": "glm-4",
      "model": "zhipu/glm-4.7",
      "api_key": "your-zhipu-key"
    }
  ],
  "gateway": {
    "host": "0.0.0.0",
    "port": 18790
  },
  "channels": {
    "wecom_aibot": {
      "enabled": true,
      "token": "abcdefghijklmnopqrst",
      "encoding_aes_key": "1234567890abcdefghijklmnopqrstuvwxyz1234567",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
      "welcome_message": "你好！我是你的AI助手，有什么可以帮你的吗？"
    }
  }
}

Regional Considerations

China-Specific Notes:

WeCom is designed for Chinese enterprise market
Servers hosted in China for compliance
Use Chinese LLM providers (Zhipu, Qwen, DeepSeek)
Content filtering may apply
Follow Chinese data protection laws
International version (WeChat Work) has limited features

Next Steps

DingTalk Channel

Another enterprise platform in China

QQ Channel

Popular personal messaging in China

Telegram Channel

International alternative

Configuration

Advanced configuration options

Get Started

Core Concepts

Commands

Configuration

Chat Channels

Features

Deployment

Advanced

​Integration Modes

​Mode 1: WeCom Bot (Group Webhook)

​Prerequisites

​Setup Instructions

​WeCom Bot Configuration

​Mode 2: WeCom App (Custom Application)

​Prerequisites

​Setup Instructions

​WeCom App Configuration

​Mode 3: WeCom AI Bot (Official AI Integration)

​Why AI Bot Mode?

​Prerequisites

​Setup Instructions

​WeCom AI Bot Configuration

​Streaming Protocol

​Access Control

​Comparison Table

​Troubleshooting

​”Signature verification failed”

​”Invalid CorpID”

​Bot doesn’t respond

​Webhook not receiving messages

​”App not found” errors

​Privacy & Security

​Data Privacy

​Complete Example

​Regional Considerations

​Next Steps

DingTalk Channel

QQ Channel

Telegram Channel

Configuration

Build docs developers (and LLMs) love

Integration Modes

Mode 1: WeCom Bot (Group Webhook)

Prerequisites

Setup Instructions

WeCom Bot Configuration

Mode 2: WeCom App (Custom Application)

Prerequisites

Setup Instructions

WeCom App Configuration

Mode 3: WeCom AI Bot (Official AI Integration)

Why AI Bot Mode?

Prerequisites

Setup Instructions

WeCom AI Bot Configuration

Streaming Protocol

Access Control

Comparison Table

Troubleshooting

”Signature verification failed”

”Invalid CorpID”

Bot doesn’t respond

Webhook not receiving messages

”App not found” errors

Privacy & Security

Data Privacy

Complete Example

Regional Considerations

Next Steps