docs: add high-usage chat app guides
This commit is contained in:
chengyongru
Xubin Ren
@@ -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).
|
||||
|
||||
|
||||
@@ -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) |
|
||||
|
||||
|
||||
@@ -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) |
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user