diff --git a/docs/users/features/channels/overview.md b/docs/users/features/channels/overview.md index 351ecbeaf..1a35b4d43 100644 --- a/docs/users/features/channels/overview.md +++ b/docs/users/features/channels/overview.md @@ -1,6 +1,6 @@ # Channels -Channels let you interact with a Qwen Code agent from messaging platforms like Telegram, instead of the terminal. You send messages from your phone or desktop chat app, and the agent responds just like it would in the CLI. +Channels let you interact with a Qwen Code agent from messaging platforms like Telegram or WeChat, instead of the terminal. You send messages from your phone or desktop chat app, and the agent responds just like it would in the CLI. ## How It Works @@ -15,7 +15,7 @@ Each channel runs as a long-lived process that bridges a messaging platform to a ## Quick Start -1. Set up a bot on your messaging platform (see the channel-specific guide, e.g., [Telegram](./telegram)) +1. Set up a bot on your messaging platform (see channel-specific guides: [Telegram](./telegram), [WeChat](./weixin)) 2. Add the channel configuration to `~/.qwen/settings.json` 3. Run `qwen channel start ` @@ -45,17 +45,18 @@ Channels are configured under the `channels` key in `settings.json`. Each channe ### Options -| Option | Required | Description | -| -------------- | -------- | -------------------------------------------------------------------------------------------------- | -| `type` | Yes | Channel type: `telegram` (more coming soon) | -| `token` | Yes | Bot token. Supports `$ENV_VAR` syntax to read from environment variables | -| `senderPolicy` | No | Who can talk to the bot: `allowlist` (default), `open`, or `pairing` | -| `allowedUsers` | No | List of user IDs allowed to use the bot (used by `allowlist` and `pairing` policies) | -| `sessionScope` | No | How sessions are scoped: `user` (default), `thread`, or `single` | -| `cwd` | No | Working directory for the agent. Defaults to the current directory | -| `instructions` | No | Custom instructions prepended to the first message of each session | -| `groupPolicy` | No | Group chat access: `disabled` (default), `allowlist`, or `open`. See [Group Chats](#group-chats) | -| `groups` | No | Per-group settings. Keys are group chat IDs or `"*"` for defaults. See [Group Chats](#group-chats) | +| Option | Required | Description | +| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `type` | Yes | Channel type: `telegram` or `weixin` | +| `token` | Telegram | Bot token. Supports `$ENV_VAR` syntax to read from environment variables. Not needed for WeChat | +| `model` | No | Model to use for this channel (e.g., `qwen3.5-plus`). Overrides the default model. Useful for multimodal models that support image input | +| `senderPolicy` | No | Who can talk to the bot: `allowlist` (default), `open`, or `pairing` | +| `allowedUsers` | No | List of user IDs allowed to use the bot (used by `allowlist` and `pairing` policies) | +| `sessionScope` | No | How sessions are scoped: `user` (default), `thread`, or `single` | +| `cwd` | No | Working directory for the agent. Defaults to the current directory | +| `instructions` | No | Custom instructions prepended to the first message of each session | +| `groupPolicy` | No | Group chat access: `disabled` (default), `allowlist`, or `open`. See [Group Chats](#group-chats) | +| `groups` | No | Per-group settings. Keys are group chat IDs or `"*"` for defaults. See [Group Chats](#group-chats) | ### Sender Policy @@ -178,6 +179,42 @@ curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" | python3 Look for `message.chat.id` in the response — group IDs are negative numbers (e.g., `-5170296765`). +## Media Support + +Channels support sending images and files to the agent, not just text. + +### Images + +Send a photo to the bot and the agent will see it — useful for sharing screenshots, error messages, or diagrams. The image is sent directly to the model as a vision input. + +To use image support, configure a multimodal model for the channel: + +```json +{ + "channels": { + "my-channel": { + "type": "telegram", + "model": "qwen3.5-plus", + ... + } + } +} +``` + +### Files + +Send a document (PDF, code file, text file, etc.) to the bot. The file is downloaded and saved to a temporary directory, and the agent is told the file path so it can read the contents using its file-reading tools. + +Files work with any model — no multimodal support required. + +### Platform differences + +| Feature | Telegram | WeChat | +| -------- | -------------------------------------------- | -------------------------------- | +| Images | Direct download via Bot API | CDN download with AES decryption | +| Files | Direct download via Bot API (20MB limit) | CDN download with AES decryption | +| Captions | Photo/file captions included as message text | Not applicable | + ## Slash Commands Channels support slash commands. Some are handled locally by the adapter: diff --git a/docs/users/features/channels/telegram.md b/docs/users/features/channels/telegram.md index c8ddba38c..9a322805e 100644 --- a/docs/users/features/channels/telegram.md +++ b/docs/users/features/channels/telegram.md @@ -73,6 +73,14 @@ To use the bot in Telegram groups: By default, the bot requires an @mention or a reply to respond in groups. Set `"requireMention": false` for a specific group to make it respond to all messages (useful for dedicated task groups). See [Group Chats](./overview#group-chats) for full details. +## Images and Files + +You can send photos and documents to the bot, not just text. + +**Photos:** Send a photo and the agent will analyze it using its vision capabilities. This requires a multimodal model — add `"model": "qwen3.5-plus"` (or another vision-capable model) to your channel config. Photo captions are passed as the message text. + +**Documents:** Send a PDF, code file, or any document. The bot downloads it and saves it locally so the agent can read it with its file tools. This works with any model. Telegram's file size limit is 20MB. + ## Tips - **Keep instructions concise-focused** — Telegram has a 4096-character message limit. Adding instructions like "keep responses short" helps the agent stay within bounds. diff --git a/docs/users/features/channels/weixin.md b/docs/users/features/channels/weixin.md new file mode 100644 index 000000000..e9fd14c82 --- /dev/null +++ b/docs/users/features/channels/weixin.md @@ -0,0 +1,102 @@ +# WeChat (Weixin) + +This guide covers setting up a Qwen Code channel on WeChat via the official iLink Bot API. + +## Prerequisites + +- A WeChat account that can scan QR codes (mobile app) +- Access to the iLink Bot platform (WeChat's official bot API) + +## Setup + +### 1. Log in via QR code + +WeChat uses QR code authentication instead of a static bot token. Run the login command: + +```bash +qwen channel configure-weixin +``` + +This will display a QR code URL. Scan it with your WeChat mobile app to authenticate. Your credentials are saved to `~/.qwen/channels/weixin/account.json`. + +### 2. Configure the channel + +Add the channel to `~/.qwen/settings.json`: + +```json +{ + "channels": { + "my-weixin": { + "type": "weixin", + "senderPolicy": "pairing", + "allowedUsers": [], + "sessionScope": "user", + "cwd": "/path/to/your/project", + "model": "qwen3.5-plus", + "instructions": "You are a concise coding assistant responding via WeChat. Keep responses under 500 characters. Use plain text only." + } + } +} +``` + +Note: WeChat channels do not use a `token` field — credentials come from the QR login step. + +### 3. Start the channel + +```bash +qwen channel start my-weixin +``` + +Open WeChat and send a message to the bot. You should see a typing indicator ("...") while the agent processes, followed by the response. + +## Images and Files + +You can send photos and documents to the bot, not just text. + +**Photos:** Send an image (screenshot, photo, etc.) and the agent will analyze it using its vision capabilities. This requires a multimodal model — add `"model": "qwen3.5-plus"` (or another vision-capable model) to your channel config. A typing indicator shows while the image is being downloaded and processed. + +**Files:** Send a PDF, code file, or any document. The bot downloads and decrypts it from WeChat's CDN, saves it locally, and the agent reads it with its file tools. This works with any model. + +## Configuration Options + +WeChat channels support all the standard channel options (see [Channel Overview](./overview#options)), plus: + +| Option | Description | +| --------- | ------------------------------------------------------------------------------ | +| `baseUrl` | Override the iLink Bot API base URL (default: `https://ilinkai.weixin.qq.com`) | + +## Key Differences from Telegram + +- **Authentication:** QR code login instead of a static bot token. Sessions can expire — the channel will pause and log a message if this happens. +- **Formatting:** WeChat only supports plain text. Markdown in agent responses is automatically stripped. +- **Typing indicator:** WeChat has a native "..." typing indicator instead of a "Working..." text message. +- **Groups:** WeChat iLink Bot is DM-only — group chats are not supported. +- **Media encryption:** Images and files are encrypted on WeChat's CDN with AES-128-ECB. The channel handles decryption transparently. + +## Tips + +- **Use plain text instructions** — Since WeChat strips all markdown, add instructions like "Use plain text only" to avoid the agent producing formatted responses that look messy. +- **Keep responses short** — WeChat message bubbles work best with concise text. Adding a character limit to your instructions helps (e.g., "Keep responses under 500 characters"). +- **Session expiry** — If you see "Session expired (errcode -14)" in the logs, your WeChat login has expired. Stop the channel and re-run `qwen channel configure-weixin` to log in again. +- **Restrict access** — Use `senderPolicy: "pairing"` or `"allowlist"` to control who can talk to the bot. See [DM Pairing](./overview#dm-pairing) for details. + +## Troubleshooting + +### "WeChat account not configured" + +Run `qwen channel configure-weixin` to log in via QR code first. + +### "Session expired (errcode -14)" + +Your WeChat login session has expired. Stop the channel and run `qwen channel configure-weixin` again. + +### Bot doesn't respond + +- Check the terminal output for errors +- Verify the channel is running (`qwen channel start my-weixin`) +- If using `senderPolicy: "allowlist"`, make sure your WeChat user ID is in `allowedUsers` + +### Images not working + +- Make sure your channel config has a `model` that supports vision (e.g., `qwen3.5-plus`) +- Check the terminal for CDN download errors — these may indicate a network issue