WeChat Bot

English | Simplified Chinese

A WeChat / IM agent project based on Wechaty.

It can route IM messages received from WeChat QR-code login, Lark IM events, Telegram Bot API polling, or WhatsApp Cloud API webhooks to ChatGPT, DeepSeek, Ollama, Claude, Pi, and other services. It can also use OpenCLI wx-cli to access local WeChat chats, contacts, group members, favorites, and Moments cache, then run statistics or AI analysis for a group chat or a specific friend.

If you want to use Pi as the project agent and WeChat, Lark, Telegram, or WhatsApp as the external communication channel, start with Pi Agent + IM Guide.

Feature Overview

Feature	Command entry	Status
WeChat QR-code IM	wb agent --im wechat --agent pi / wb start --serve pi	Available. Logs in by QR code and replies to allowlisted messages
Pi as project agent	wb agent --im wechat/lark/telegram/whatsapp --agent pi	Available. Single-turn non-interactive replies by default
Local WeChat chats / contacts / group members	wb wx sessions, wb wx history, wb wx members	Integrated through OpenCLI wx-cli
Local Moments cache	wb wx sns-feed, wb wx sns-search	Integrated through OpenCLI wx-cli
Group / friend analysis	wb analyze --room "Group name", wb analyze --friend "Friend alias"	Supports local statistics and AI deep analysis
Lark IM	wb lark login, wb lark messages, wb lark send, wb lark agent	Supports login, read, search, send, and event-driven auto-replies
Telegram IM	wb telegram agent, wb telegram send	Supports Bot API long-polling receive and send
WhatsApp IM	wb whatsapp agent, wb whatsapp send	Supports WhatsApp Cloud API webhook receive and send
Multi-model replies	--serve ChatGPT/deepseek/ollama/pi/...	Reuses the existing provider mechanism

Quick Start: Pi + WeChat IM

npm i
cp .env.example .env
npm link

Configure at least the following values in .env:

BOT_NAME='@Your WeChat nickname'
ALIAS_WHITELIST='Friend alias allowed for private chat'
ROOM_WHITELIST='Group name allowed for access'

PI_BIN='pi'
PI_AGENT_ARGS='--print --no-session'
WECHAT_STORE_MESSAGES='true'

Start the agent:

wb agent --im wechat --agent pi

When a QR code appears in the terminal, scan it with WeChat. The message pipeline is:

WeChat QR-code login -> Wechaty receives message -> local JSONL capture -> Pi agent reply -> WeChat IM sends reply

Trigger rules:

• Private chats: the sender alias or nickname must be in ALIAS_WHITELIST.
• Group chats: the group name must be in ROOM_WHITELIST, and the message must mention @BOT_NAME.
• Non-text messages are not automatically sent to the reply pipeline.

Note: WeChat Web protocols carry account risk, including warnings or bans. Use this only with accounts and scenarios where you explicitly accept the risk. Keep allowlists and usage scope narrow.

Contributors

PRs for more AI services, better integrations, and stronger implementations are welcome.

Important WeChat Protocol Warning

WeChat has recently become very strict about this type of usage. The default protocol can trigger WeChat warnings or account bans. Use it carefully. The author of the padlocal protocol is no longer maintaining it, so switch to a more stable protocol yourself if needed.

Supported Reply / Agent Services

If you only use wb wx ... to access local WeChat data, or only use wb lark ... to operate Lark IM, you do not need to configure an LLM.

If you want automatic WeChat replies or wb analyze deep analysis, choose a --serve service. Current options include ChatGPT, doubao, deepseek, Kimi, Xunfei, deepseek-free, 302AI, dify, ollama, tongyi, claude, and pi.

• pi

  Pi is suitable as the project agent and can communicate through WeChat, Lark, Telegram, or WhatsApp IM:

  PI_BIN='pi'
  PI_NPM_PACKAGE='@earendil-works/pi-coding-agent'
  PI_AGENT_ARGS='--print --no-session'

  If your machine does not have a global pi command, leave PI_BIN empty. The project will start Pi through npx --yes @earendil-works/pi-coding-agent.

• deepseek

  Get your api key from the DeepSeek platform, then put it in .env:

  DEEPSEEK_FREE_TOKEN='your key'

• ChatGPT

  Get your api key from OpenAI API keys.

  This is a paid service. If requests fail, make sure your terminal proxy works and your OpenAI account has billing available.

  # Copy .env.example to .env
  cp .env.example .env
  # Fill in .env
  OPENAI_API_KEY='your key'

• Doubao

  Doubao Seed 1.6 supports image input and deep thinking. After registering and logging in to Volcano Engine, select a Doubao model, choose API access, and get an API key.

  # Copy .env.example to .env
  cp .env.example .env
  # Fill in .env
  DOUBAO_API_KEY='your key'
  # Test whether the API works
  node src/doubao/__test__.js

• Tongyi Qianwen

  Tongyi Qianwen is an AI service from Alibaba Cloud. After getting your API key, fill in .env:

  # Copy .env.example to .env
  cp .env.example .env
  # Fill in .env
  # Tongyi URL, including the URI path
  TONGYI_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
  # Tongyi API key
  TONGYI_API_KEY = ''
  # Tongyi model
  TONGYI_MODEL='qwen-plus'

• Xunfei

  Apply for a key from Xunfei. Be careful not to mix up the several Xunfei configuration keys. For service errors, see issues/170 and issues/180.

• Kimi

  Get a key from Kimi API keys. Kimi is currently integrated at a basic level. PRs for file upload and other improvements are welcome.

• dify

  Create an app at dify, get your API key, and fill in .env. Self-hosted Dify deployments are also supported.

  # Copy .env.example to .env
  cp .env.example .env
  # Fill in .env
  DIFY_API_KEY='your key'
  # For self-hosted Dify, update the following value in .env
  # DIFY_URL='https://[your self-hosted URL]'

• ollama

  Ollama is a local AI service. Its API is close to OpenAI's API, but configuration differs from cloud services.

  # Copy .env.example to .env
  cp .env.example .env
  # Fill in .env
  OLLAMA_URL='http://127.0.0.1:11434/api/chat'
  OLLAMA_MODEL='qwen2.5:7b'
  OLLAMA_SYSTEM_MESSAGE='You are a personal assistant.'

• 302.AI

  302.AI is an AI aggregation platform. Add an API from 302.AI APIs, then configure the API key in .env:

  _302AI_API_KEY = 'xxxx'
  _302AI_MODEL= 'gpt-4o-mini'

  You can choose the model yourself. Users should evaluate platform cost, payment flow, and service quality before using it.

• claude

  Register on the Anthropic Console, get an API key, then configure:

  # Copy .env.example to .env if it does not already exist
  cp .env.example .env
  
  # Edit .env and add Claude settings
  CLAUDE_API_VERSION = '2023-06-01'
  CLAUDE_API_KEY = 'your API key'
  CLAUDE_MODEL = 'claude-3-5-sonnet-latest'
  # System prompt
  CLAUDE_SYSTEM = ''

• Other

  In theory, APIs compatible with OpenAI's format can be used by configuring the corresponding API key, model, and proxy URL in .env.

API Resources / Platforms

• gpt4free
• chatanywhere

Development / Usage

Make sure your development environment has nodejs installed. The required version is Node.js >= v18.0. Older versions can fail at runtime. An LTS version is recommended.

1. Install dependencies

For users in mainland China, switching to the Taobao npm mirror before installing dependencies may help: npm config set registry https://registry.npmmirror.com For flexible registry switching, you can use prm-cli.

npm i

# Optional: register wb as a local command
npm link

If you do not want to run npm link, replace every wb ... command below with:

npm run start -- ...

2. Configure .env

cp .env.example .env

Minimum usable configuration:

BOT_NAME='@Your WeChat nickname'
ALIAS_WHITELIST='Friend alias 1,Friend nickname 2'
ROOM_WHITELIST='Group name 1,Group name 2'
AUTO_REPLY_PREFIX=''

WECHAT_DATA_DIR='.data/wechat'
WECHAT_STORE_MESSAGES='true'

PI_BIN='pi'
PI_AGENT_ARGS='--print --no-session'

3. Start WeChat IM

Pi agent mode:

wb agent --im wechat --agent pi

Equivalent commands:

wb start --serve pi
npm run agent
npm run start -- start --serve pi

Traditional model reply mode:

wb start --serve ollama
wb start --serve ChatGPT
wb start --serve deepseek

After startup, a QR code appears in the terminal. Scan it to log in to WeChat. After login, received WeChat messages are appended to:

.data/wechat/messages.jsonl

4. Local WeChat Data and Moments

OpenCLI wx-cli is passed through by wb wx ... and is used to access local WeChat cache:

wb wx init
wb wx sessions
wb wx history
wb wx search
wb wx contacts
wb wx members
wb wx stats
wb wx favorites
wb wx sns-feed
wb wx sns-search
wb wx sns-notifications
wb wx help

Common flows:

# Initialize local WeChat data access
wb wx init

# View recent sessions and chat history
wb wx sessions
wb wx history

# View group members and chat statistics
wb wx members
wb wx stats

# View Moments cache and search Moments text
wb wx sns-feed
wb wx sns-search

5. Group / Friend Analysis

Command-line analysis:

# Local statistics only, without calling AI
wb analyze --room "Group name" --stats-only
wb analyze --friend "Friend alias" --stats-only

# Call a selected service for deep analysis
wb analyze --room "Group name" --serve pi
wb analyze --friend "Friend alias" --serve ollama

Built-in commands in WeChat chats only work for allowlisted contacts or allowlisted groups by default:

/stats group GroupName
/analyze friend FriendAlias

/stats only reads local JSONL and does not call AI. /analyze sends recent message samples to the current serve service or agent. For private chats, prefer a local model or local Pi configuration.

6. Lark IM

Lark IM is integrated through lark-cli:

# Generate a device-flow authorization link / QR-code info
wb lark login --no-wait

# Check authorization status
wb lark status

# Read / search / send messages
wb lark messages --chat-id oc_xxx
wb lark search --query "keyword"
wb lark send --chat-id oc_xxx --text "hello"

To let Pi or another provider reply to Lark messages through the event stream, configure:

LARK_AGENT_IDENTITY='bot'
LARK_AGENT_EVENT_KEY='im.message.receive_v1'
LARK_AGENT_CHAT_TYPES='p2p,group'
LARK_AGENT_MESSAGE_TYPES='text,post'
LARK_AGENT_CHAT_WHITELIST=''
LARK_AGENT_USER_WHITELIST=''
LARK_AGENT_REPLY_PREFIX=''
LARK_AGENT_GROUP_MENTION_NAME=''
LARK_AGENT_GROUP_AUTO_REPLY='false'

Then start:

wb agent --im lark --agent pi
# or
wb lark agent --agent pi

The Lark event path uses lark-cli event consume im.message.receive_v1 --as bot. Private chats are replied to by default unless you set a chat or user allowlist. Group chats require LARK_AGENT_CHAT_WHITELIST and one of these triggers: LARK_AGENT_REPLY_PREFIX, LARK_AGENT_GROUP_MENTION_NAME, or LARK_AGENT_GROUP_AUTO_REPLY=true.

Before using event replies, make sure the Lark app has enabled the im.message.receive_v1 event in the developer console and has the required IM scopes.

7. Telegram Bot API

Telegram uses the official Bot API with long polling:

TELEGRAM_BOT_TOKEN='123456:bot-token'
TELEGRAM_AGENT_CHAT_TYPES='private,group,supergroup'
TELEGRAM_AGENT_CHAT_WHITELIST=''
TELEGRAM_AGENT_USER_WHITELIST=''
TELEGRAM_AGENT_REPLY_PREFIX=''
TELEGRAM_AGENT_GROUP_MENTION_NAME='@your_bot'
TELEGRAM_AGENT_GROUP_AUTO_REPLY='false'

Start:

wb agent --im telegram --agent pi
# or
wb telegram agent --agent pi

Private chats are replied to by default unless you set a chat or user allowlist. Group and supergroup chats require a chat allowlist and one of these triggers: reply prefix, bot mention name, or TELEGRAM_AGENT_GROUP_AUTO_REPLY=true.

You can send a test message with:

wb telegram send --chat-id 123456 --text "hello"

8. WhatsApp Cloud API

WhatsApp uses the official Cloud API. Incoming messages are received through a webhook, so the local server must be reachable from Meta through a public HTTPS URL.

WHATSAPP_ACCESS_TOKEN='your access token'
WHATSAPP_PHONE_NUMBER_ID='your phone_number_id'
WHATSAPP_VERIFY_TOKEN='your webhook verify token'
WHATSAPP_GRAPH_API_VERSION='v23.0'
WHATSAPP_WEBHOOK_PORT='3000'
WHATSAPP_WEBHOOK_PATH='/webhook/whatsapp'
WHATSAPP_AGENT_REPLY_PREFIX=''

Start the webhook server:

wb agent --im whatsapp --agent pi
# or
wb whatsapp agent --agent pi

Configure the webhook callback URL in Meta as:

https://your-public-domain.example/webhook/whatsapp

Use the same WHATSAPP_VERIFY_TOKEN value in Meta's webhook verification form. WhatsApp replies only support inbound text messages by default.

You can send a test message with:

wb whatsapp send --to 15551234567 --text "hello"

9. Pi / OpenCLI Passthrough

wb pi -- --help
wb pi -- --print "Analyze the current project structure"

wb opencli -- --help
wb opencli -- wx-cli help

10. Tests

npm run test:analysis
node ./cli.js --help
node ./cli.js wx help
node ./cli.js pi -- --help

If you use cloud services such as OpenAI, Claude, or Kimi, make sure the corresponding API key, balance, and network proxy are available.

What You Need to Customize

Many users assume the bot should automatically send and receive every message after startup. It does not. To avoid replying to every incoming message, the project intentionally has trigger restrictions.

Customize the following values:

• BOT_NAME: the WeChat nickname of the bot account, in a format similar to @Cola.
• ALIAS_WHITELIST: friend aliases or nicknames allowed for auto-reply.
• ROOM_WHITELIST: group chat names allowed for auto-reply.
• AUTO_REPLY_PREFIX: optional. Auto-reply is triggered only when the message matches this prefix.
• PI_AGENT_ARGS: arguments used when Pi runs as the IM agent. The default is --print --no-session.
• For deeper business logic, see src/wechaty/sendMessage.js and src/platforms/wechat/commandRouter.js.

Edit these values in .env. Example:

# Allowlist configuration
# Define the bot name. This avoids replying to too many group messages.
# Keep the @ prefix and append the WeChat nickname of the bot account.
BOT_NAME=@Cola
# Contact allowlist
ALIAS_WHITELIST=WeChatName1,Alias2
# Group chat allowlist
ROOM_WHITELIST=Group1,Group2
# Auto-reply prefix matching. For text messages, auto-reply is triggered only
# when the specified prefix matches. Empty or unset values disable this setting.
# Matching rule: group messages remove ${BOT_NAME} and trim before prefix matching;
# private messages are trimmed directly before prefix matching.
AUTO_REPLY_PREFIX=''

# Pi agent
PI_BIN='pi'
PI_AGENT_ARGS='--print --no-session'

Auto-reply is no longer limited to chatgpt. Use --serve to choose different services, such as pi, ollama, deepseek, claude, or ChatGPT.

Notes

Recent WeChat review is strict. Many users have reported plugin warnings. Because the project uses a free Web protocol by default, WeChat can detect it easily. Consider using a pad protocol or buying an enterprise protocol yourself to reduce account-ban risk.

Reference change: https://github.com/wangrongding/wechat-bot/pull/263/files

Pad protocol channel shared by Wechaty, purchase carefully: http://pad-local.com

The underlying wechaty dependency itself is not actively maintained. Community feedback says the pad protocol can currently work, but frequent login/logout can still trigger warnings. Avoid buying a very long subscription at once.

FAQ

The following are the author's WeChat and group QR codes. Please describe your purpose clearly when adding the author.

Runtime errors

First check the following:

• Pull the latest code and reinstall dependencies. If necessary, delete the lock file and node_modules.

• It is usually better not to set an npm mirror while installing dependencies.

• If Puppeteer installation fails, set the environment variable:

  # Mac
  export PUPPETEER_SKIP_DOWNLOAD='true'
  
  # Windows
  SET PUPPETEER_SKIP_DOWNLOAD='true'

• If you use a cloud model, make sure the terminal network can access the corresponding model service. Enable a global proxy or configure a terminal proxy manually.

  # Set proxy
  export https_proxy=http://127.0.0.1:your_proxy_port;export http_proxy=http://127.0.0.1:your_proxy_port;export all_proxy=socks5://127.0.0.1:your_proxy_port
  # Then run a service test, or first check whether the CLI works
  node ./cli.js --help

  

• If you use OpenAI / Claude / Kimi or another cloud model, confirm that the API key, account balance, model name, and proxy settings are correct.

• Configure .env, especially BOT_NAME, allowlists, and parameters required by the current --serve service.

• Run npm run test:analysis to verify the local analysis module. Run node ./cli.js --help to verify the CLI.

• Run wb agent --im wechat --agent pi or wb start --serve <service> to start WeChat QR-code login.

• Run wb agent --im lark --agent pi or wb lark agent --agent pi to start Lark event-based replies.

You can also refer to this issue.

• How to use it? After customization, when someone mentions you in an allowlisted group, or an allowlisted private contact sends you a message, auto-reply is triggered.
• Runtime error? Check whether the Node version meets the requirement. If not, upgrade Node. Check whether dependencies are fully installed. Users in mainland China can switch npm mirrors and reinstall dependencies. prm-cli can switch registries quickly.
• How to adjust conversation mode? Prefer switching services with --serve. For custom business logic, see sendMessage.js, commandRouter.js, and the corresponding provider implementation.

Docker Deployment

docker build . -t wechat-bot

docker run -d --rm --name wechat-bot -v $(pwd)/.env:/app/.env wechat-bot

• If Node repeatedly times out during docker build, download a Node.js image to your local image registry first, then change node:19 in Dockerfile to your local Node.js image version.

Star History Chart

This project became No. 1 on GitHub Trending on 2023-02-13.

License

MIT.