From 7204d88a4cdb3ee3a5b5341c9683c14c4df86af8 Mon Sep 17 00:00:00 2001 From: chengyongru Date: Wed, 8 Jul 2026 16:32:45 +0800 Subject: [PATCH] docs: add high-usage chat app guides --- docs/README.md | 3 + docs/chat-apps.md | 3 + docs/guides/README.md | 3 + docs/guides/chat-app-ai-agent.md | 3 + docs/guides/feishu-ai-agent.md | 120 +++++++++++++++++++++++++++++++ docs/guides/qq-ai-agent.md | 102 ++++++++++++++++++++++++++ docs/guides/whatsapp-ai-agent.md | 107 +++++++++++++++++++++++++++ 7 files changed, 341 insertions(+) create mode 100644 docs/guides/feishu-ai-agent.md create mode 100644 docs/guides/qq-ai-agent.md create mode 100644 docs/guides/whatsapp-ai-agent.md diff --git a/docs/README.md b/docs/README.md index aec1660e..9eb2c32e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -52,7 +52,10 @@ Platform-specific chat guides: [`Telegram`](./guides/telegram-ai-agent.md), [`Discord`](./guides/discord-ai-agent.md), [`Slack`](./guides/slack-ai-agent.md), +[`Feishu`](./guides/feishu-ai-agent.md), +[`WhatsApp`](./guides/whatsapp-ai-agent.md), [`WeChat`](./guides/wechat-ai-agent.md), +[`QQ`](./guides/qq-ai-agent.md), [`Email`](./guides/email-ai-agent.md), and [`Mattermost`](./guides/mattermost-ai-agent.md). diff --git a/docs/chat-apps.md b/docs/chat-apps.md index 15abea47..70f9c533 100644 --- a/docs/chat-apps.md +++ b/docs/chat-apps.md @@ -9,7 +9,10 @@ a focused setup path for one platform, start with a guide: | Telegram | [Build a Telegram AI Agent with nanobot](./guides/telegram-ai-agent.md) | | Discord | [Build a Discord AI Agent with nanobot](./guides/discord-ai-agent.md) | | Slack | [Build a Slack AI Agent with nanobot](./guides/slack-ai-agent.md) | +| Feishu | [Build a Feishu AI Agent with nanobot](./guides/feishu-ai-agent.md) | +| WhatsApp | [Build a WhatsApp AI Agent with nanobot](./guides/whatsapp-ai-agent.md) | | WeChat | [Build a WeChat AI Agent with nanobot](./guides/wechat-ai-agent.md) | +| QQ | [Build a QQ AI Agent with nanobot](./guides/qq-ai-agent.md) | | Email | [Build an Email AI Agent with nanobot](./guides/email-ai-agent.md) | | Mattermost | [Build a Mattermost AI Agent with nanobot](./guides/mattermost-ai-agent.md) | diff --git a/docs/guides/README.md b/docs/guides/README.md index 7925379e..df2a406e 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -23,7 +23,10 @@ edge cases. | Connect Telegram | [Telegram AI agent](./telegram-ai-agent.md) | | Connect Discord | [Discord AI agent](./discord-ai-agent.md) | | Connect Slack | [Slack AI agent](./slack-ai-agent.md) | +| Connect Feishu | [Feishu AI agent](./feishu-ai-agent.md) | +| Connect WhatsApp | [WhatsApp AI agent](./whatsapp-ai-agent.md) | | Connect WeChat | [WeChat AI agent](./wechat-ai-agent.md) | +| Connect QQ | [QQ AI agent](./qq-ai-agent.md) | | Connect Email | [Email AI agent](./email-ai-agent.md) | | Connect Mattermost | [Mattermost AI agent](./mattermost-ai-agent.md) | | Run from Python | [Python AI agent SDK](./python-ai-agent-sdk.md) | diff --git a/docs/guides/chat-app-ai-agent.md b/docs/guides/chat-app-ai-agent.md index 83cb43b0..22bf4880 100644 --- a/docs/guides/chat-app-ai-agent.md +++ b/docs/guides/chat-app-ai-agent.md @@ -29,7 +29,10 @@ Then choose one platform guide: - [Telegram AI agent](./telegram-ai-agent.md) - [Discord AI agent](./discord-ai-agent.md) - [Slack AI agent](./slack-ai-agent.md) +- [Feishu AI agent](./feishu-ai-agent.md) +- [WhatsApp AI agent](./whatsapp-ai-agent.md) - [WeChat AI agent](./wechat-ai-agent.md) +- [QQ AI agent](./qq-ai-agent.md) - [Email AI agent](./email-ai-agent.md) - [Mattermost AI agent](./mattermost-ai-agent.md) diff --git a/docs/guides/feishu-ai-agent.md b/docs/guides/feishu-ai-agent.md new file mode 100644 index 00000000..b7b0f387 --- /dev/null +++ b/docs/guides/feishu-ai-agent.md @@ -0,0 +1,120 @@ +# Build a Feishu AI Agent with nanobot + +This guide connects nanobot to Feishu or Lark through the `feishu` channel. The +channel uses a WebSocket long connection, so the first setup does not require a +public webhook URL. + +## What this guide builds + +- a Feishu/Lark bot app connected to nanobot +- the `feishu` channel enabled in `config.json` +- one pairing-approved Feishu or Lark user +- mention-only group behavior for first deployment + +## Prerequisites + +- A working local nanobot reply: + +```bash +nanobot agent -m "Hello!" +``` + +- A Feishu or Lark account that can create or approve bot apps. +- Permission to run `nanobot gateway` continuously. + +## Install nanobot + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +``` + +## Enable the Feishu channel + +Install the optional channel dependency: + +```bash +nanobot plugins enable feishu +``` + +The easiest path is QR login: + +```bash +nanobot channels login feishu +``` + +Open the printed URL or scan the QR code. nanobot writes the generated `appId`, +`appSecret`, `domain`, and `enabled` fields into the active config. + +If QR login is unavailable, create a Feishu/Lark app manually and merge this +shape into `~/.nanobot/config.json`: + +```json +{ + "channels": { + "feishu": { + "enabled": true, + "appId": "cli_xxx", + "appSecret": "xxx", + "groupPolicy": "mention", + "streaming": true, + "domain": "feishu" + } + } +} +``` + +Omitting `allowFrom` enables pairing-only mode. A new user should DM the bot, +get a pairing code, and be approved before using the bot normally. + +For manual apps, enable the Bot capability, receive-message events, and Long +Connection mode. If your app cannot get the `cardkit:card:write` permission, +set `"streaming": false`. + +## Run nanobot gateway + +```bash +nanobot channels status +nanobot gateway +``` + +## Test a message + +DM the bot first. It should return a pairing code. Approve it from a trusted +local surface: + +```bash +nanobot agent -m "/pairing approve ABCD-EFGH" +``` + +After approval, DM the bot again or mention it in a group chat: + +```text +@nanobot Hello from Feishu +``` + +## Security notes + +- Prefer pairing-only mode for first setup. Add `allowFrom` only when you want a + static allowlist. +- Keep `groupPolicy` as `"mention"` before inviting the bot into busy groups. +- Store app secrets through environment variables for deployed services. +- Review file, shell, and web tool access before adding more users. + +## Troubleshooting + +- If QR login is unavailable, use manual app setup from the full chat-apps + reference. +- If streaming cards fail, confirm `cardkit:card:write` or set + `"streaming": false`. +- If no messages arrive, check Feishu/Lark event permissions, Long Connection + mode, and `nanobot gateway --verbose`. +- If a first DM returns a pairing code, approve it before testing normal + replies. + +## Next: memory, automations, MCP tools + +- [Chat Apps reference](../chat-apps.md) +- [Pairing](../configuration.md#pairing) +- [AI Agent Memory](./ai-agent-memory.md) +- [Configure MCP tools](./configure-mcp-tools.md) diff --git a/docs/guides/qq-ai-agent.md b/docs/guides/qq-ai-agent.md new file mode 100644 index 00000000..9ff110e4 --- /dev/null +++ b/docs/guides/qq-ai-agent.md @@ -0,0 +1,102 @@ +# Build a QQ AI Agent with nanobot + +This guide connects nanobot to QQ through the official `qq` channel. The +official channel uses the botpy SDK and currently focuses on private messages. +For QQ group chat and OneBot v11 workflows, use the Napcat section in the full +chat-apps reference. + +## What this guide builds + +- a QQ bot application +- the `qq` channel enabled in nanobot +- one pairing-approved QQ private sender +- a running nanobot gateway + +## Prerequisites + +- A working local nanobot reply: + +```bash +nanobot agent -m "Hello!" +``` + +- Access to the QQ Open Platform. +- A QQ account added to the bot sandbox for testing. + +## Install nanobot + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +``` + +## Enable the QQ channel + +Install the optional channel dependency: + +```bash +nanobot plugins enable qq +``` + +In the QQ Open Platform, create a bot application and copy the AppID and +AppSecret. Add your QQ account to the sandbox test members, then merge this +snippet into `~/.nanobot/config.json`: + +```json +{ + "channels": { + "qq": { + "enabled": true, + "appId": "YOUR_APP_ID", + "secret": "YOUR_APP_SECRET", + "msgFormat": "plain" + } + } +} +``` + +Omitting `allowFrom` enables pairing-only mode. A new private sender should get +a pairing code before normal agent access. + +## Run nanobot gateway + +```bash +nanobot channels status +nanobot gateway +``` + +## Test a message + +Send the QQ bot a private message from a sandbox account. It should return a +pairing code. Approve it from a trusted local surface: + +```bash +nanobot agent -m "/pairing approve ABCD-EFGH" +``` + +Send the message again after approval. + +## Security notes + +- Prefer pairing-only mode for first setup. Add `allowFrom` only when you want a + static allowlist. +- Keep sandbox testing separate from production publishing. +- Store QQ AppSecret through environment variables for deployed services. +- Use Napcat only when you intentionally need a QQ account bridge and group chat + features. + +## Troubleshooting + +- If private messages do not arrive, confirm the sender is in the QQ bot sandbox + and the gateway is running. +- If output formatting is unreliable, keep `msgFormat` as `"plain"`. +- If a first private message returns a pairing code, approve it before testing + normal replies. +- If you need QQ groups, see the Napcat section in the full chat-apps reference. + +## Next: memory, automations, MCP tools + +- [Chat Apps reference](../chat-apps.md) +- [Pairing](../configuration.md#pairing) +- [AI Agent Memory](./ai-agent-memory.md) +- [Configure MCP tools](./configure-mcp-tools.md) diff --git a/docs/guides/whatsapp-ai-agent.md b/docs/guides/whatsapp-ai-agent.md new file mode 100644 index 00000000..8c1748c9 --- /dev/null +++ b/docs/guides/whatsapp-ai-agent.md @@ -0,0 +1,107 @@ +# Build a WhatsApp AI Agent with nanobot + +This guide connects nanobot to WhatsApp through the `whatsapp` channel. The +channel links as a WhatsApp device and uses the same nanobot agent runtime, +tools, memory, and workspace as the CLI and WebUI. + +## What this guide builds + +- WhatsApp optional dependencies installed +- a linked WhatsApp device session +- the `whatsapp` channel enabled in `config.json` +- one pairing-approved WhatsApp sender + +## Prerequisites + +- A working local nanobot reply: + +```bash +nanobot agent -m "Hello!" +``` + +- A WhatsApp account that can link a new device. +- A machine that can keep `nanobot gateway` running. + +## Install nanobot + +```bash +python -m pip install nanobot-ai +nanobot onboard --wizard +``` + +## Enable the WhatsApp channel + +Install the optional channel dependency: + +```bash +nanobot plugins enable whatsapp +``` + +Link WhatsApp as a device: + +```bash +nanobot channels login whatsapp +``` + +Scan the QR code from WhatsApp -> Settings -> Linked Devices. + +Merge this snippet into `~/.nanobot/config.json`: + +```json +{ + "channels": { + "whatsapp": { + "enabled": true, + "groupPolicy": "mention" + } + } +} +``` + +Omitting `allowFrom` enables pairing-only mode for private chats. `groupPolicy` +defaults to `"open"` in the channel, but `"mention"` is safer for a first +deployment. + +## Run nanobot gateway + +```bash +nanobot channels status +nanobot gateway +``` + +## Test a message + +Send the bot a private WhatsApp message. It should return a pairing code. +Approve it from a trusted local surface: + +```bash +nanobot agent -m "/pairing approve ABCD-EFGH" +``` + +Send the message again after approval. The reply should use the same model and +workspace as your local CLI check. + +## Security notes + +- Treat the WhatsApp session database as account access. +- Prefer pairing-only mode for first setup. Add `allowFrom` only when you want a + static allowlist. +- Keep `groupPolicy` as `"mention"` before adding the bot to groups. +- Avoid `allowFrom: ["*"]` unless the bot is intentionally public or isolated. + +## Troubleshooting + +- If QR linking fails, rerun `nanobot channels login whatsapp`. +- If you are migrating from the old bridge, remove `bridgeUrl` and + `bridgeToken`, then re-login. +- If a sender appears as a LID instead of a phone number, let nanobot learn the + mapping at runtime or use `lidMappings` in the full reference. +- If a first private message returns a pairing code, approve it before testing + normal replies. + +## Next: memory, automations, MCP tools + +- [Chat Apps reference](../chat-apps.md) +- [Pairing](../configuration.md#pairing) +- [Secure local AI agent](./secure-local-ai-agent.md) +- [Deployment](../deployment.md)