Your lightweight open-source personal agent.
Chat Apps for Self-Hosted AI Agents
Connect nanobot to Telegram, Discord, Slack, WeChat, Email, Mattermost, Linear, and other chat platforms. This page is the full chat-channel reference. If you want a focused setup path for one platform, start with a guide:
| Platform | Guide |
|---|---|
| Telegram | Build a Telegram AI Agent with nanobot |
| Discord | Build a Discord AI Agent with nanobot |
| Slack | Build a Slack AI Agent with nanobot |
| Feishu | Build a Feishu AI Agent with nanobot |
| Build a WhatsApp AI Agent with nanobot | |
| WhatsApp Agent Platform | Connect nanobot to WhatsApp Agent Platform |
| Build a WeChat AI Agent with nanobot | |
| Build a QQ AI Agent with nanobot | |
| Build an Email AI Agent with nanobot | |
| Mattermost | Build a Mattermost AI Agent with nanobot |
| Linear | Use nanobot as a native Linear agent |
Want to build your own channel? See the Channel Package Guide.
Before configuring a chat app, make sure the local CLI path works:
nanobot agent -m "Hello!"
If that fails, fix installation, config, provider, or model setup first with quick-start.md, providers.md, and troubleshooting.md. Chat apps require nanobot gateway to stay running after the channel is configured.
Recommended Setup in the WebUI
For normal local setup, let the WebUI write and validate the channel config:
- Run
nanobot webui. - Open Channels.
- Search for the platform and open its setup panel.
- Follow the credential fields or QR flow. The screen tells you which platform-side token, permission, account, or URL it needs.
- Let nanobot install the optional channel support when prompted.
- Restart from the WebUI if it reports that a restart is required.
- Send a private test message. If the channel returns a pairing code, approve the pending request in the WebUI and send the message again.
If your installed stable release does not show Channels, continue with the manual setup pattern below or install current source.
Optional package installation is available to a same-machine WebUI by default. Remote browser clients cannot change the Python environment unless an administrator explicitly enables that capability. Run nanobot plugins enable <channel> locally when the guided install is unavailable.
The sections below explain what each chat platform requires and provide manual config for deployments that manage config.json directly.
[!NOTE] If you are upgrading from a version where chat app SDKs were installed by default, enable the channel in the same Python environment so nanobot installs its manifest-declared dependencies:
nanobot plugins enable <channel>Replace
<channel>with names such astelegram,slack,feishu,dingtalk,matrix,napcat,weixin,wecom,msteams, orwhatsapp_agent. To turn a channel off later, runnanobot plugins disable <channel>. nanobot keeps the saved settings, but stops loading that channel after the next restart.
Manual Setup Pattern
Manual configuration
Most examples below are snippets to merge into ~/.nanobot/config.json. When a snippet includes allowFrom, it is showing a static allowlist. For pairing-based access on channels with a common sender allowlist, omit allowFrom. Slack and Mattermost instead use dm.policy: "allowlist" with an empty dm.allowFrom for DM pairing; their group policies are independent of DM approval.
Every chat app uses the same shape:
- Create or prepare the bot/account in the chat platform.
- Copy the token, secret, QR login state, webhook URL, or account ID that platform gives you.
- Merge that platform's JSON snippet into
~/.nanobot/config.json. - For DM pairing, use the channel-specific policy described above, let the first DM receive a pairing code, then approve it with
/pairing approve <code>. - For channels without pairing, such as Email, keep access narrow with
allowFromor the platform-specific allow list. - Check that nanobot can see the configured channel:
nanobot channels status
- Start the gateway and leave that terminal running:
nanobot gateway
- Send a test DM. If the bot returns a pairing code, approve it and send the message again. In group chats, follow that channel's
groupPolicybehavior: many channels default to mention-only, while Matrix and WhatsApp default to open group replies.
If nanobot channels status does not show the channel as enabled, the config snippet is in the wrong place, the channel name is misspelled, or the config file you edited is not the one nanobot is reading. If the channel is enabled but messages do not arrive, run nanobot gateway --verbose and compare the platform-side credentials, event permissions, and allow lists.
allowFrom: ["*"]bypasses pairing and allows anyone who can reach that channel to talk to the bot. Use it only when that is intentional, or temporarily while testing in a private sandbox.
| Channel | What you need |
|---|---|
| Telegram | Bot token from @BotFather |
| Discord | Bot token + Message Content intent |
QR code scan (nanobot channels login whatsapp) |
|
| WhatsApp Agent Platform | Agent API token from WhatsApp → Settings → Agents |
| WeChat (Weixin) | QR code scan (nanobot channels login weixin) |
| Feishu | QR code scan (nanobot channels login feishu) or App ID + App Secret |
| DingTalk | App Key + App Secret |
| Slack | Bot token + App-Level token |
| Matrix | Homeserver URL + Access token |
| IMAP/SMTP credentials | |
QR code scan (nanobot channels login qq) or App ID + App Secret |
|
| Napcat (QQ) | Napcat Forward WebSocket URL + access token |
| Wecom | Bot ID + Bot Secret |
| Microsoft Teams | App ID + App Password + public HTTPS endpoint |
| Mochat | Claw token (auto-setup available) |
| Signal | signal-cli daemon + phone number |
| Linear | Private OAuth app + public HTTPS callback and webhook URLs |
Linear
Linear is a native Agent channel rather than a comment bot. A user starts a task by explicitly mentioning the installed nanobot app in an issue. Follow-up prompts inside that Agent Session continue the same nanobot session without another mention. Ordinary issue comments do not invoke nanobot.
The native Agent API is webhook-based. Linear must reach a public HTTPS URL. An HTTPS tunnel can forward requests to nanobot's local listener without a public IP; a publicly reachable server can use a reverse proxy. Use a fixed hostname for ongoing use. Temporary tunnels also work for testing, but a hostname change requires updating nanobot's public URL and the app's callback and webhook URLs.
The recommended setup is Channels → Linear. Enter the public URL and wait for automatic saving, select Create prefilled Linear app, create the app, then copy its Client ID, Client Secret, and Webhook Signing Secret back into nanobot. Leave each secret field to save it. Once the settings are saved, choose Connect Linear. OAuth requests only read, write, and app:mentionable; it deliberately does not request app:assignable so a new task must begin with an @mention.
See the native Linear agent guide for the complete setup, tunnel examples, security model, and troubleshooting.
Telegram
Recommended WebUI setup
- Create a bot with
@BotFatherand copy its token. - Run
nanobot webui, then open Channels → Telegram. - Paste the token. If the gateway cannot reach Telegram directly, set the address in Settings → Advanced → Shared proxy, then enable Use proxy in Telegram's advanced options.
- Save and enable Telegram, then send the bot a direct message.
The configuration badge means nanobot found a saved token. The live connection check is separate, so a temporary Telegram or proxy outage does not make an existing configuration disappear. Saved tokens and proxy URLs remain masked.
See the step-by-step Telegram guide for pairing and troubleshooting.
Manual setup
Install the optional channel dependency:
nanobot plugins enable telegram
1. Create a bot
- Open Telegram, search
@BotFather - Send
/newbot, follow prompts - Copy the token
2. Configure
{
"channels": {
"telegram": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allowFrom": ["YOUR_USER_ID"]
}
}
}
If the gateway cannot reach Telegram directly, set the shared address and enable it for Telegram:
{
"network": { "proxy": "http://127.0.0.1:7890" },
"channels": {
"telegram": {
"useProxy": true
}
}
}
HTTP, HTTPS, SOCKS5, and SOCKS5H proxy URLs are accepted. Treat a proxy URL containing a username or password as a secret.
You can find your User ID in Telegram settings. It is shown as
@yourUserId. Copy this value without the@symbol and paste it into the config file.
richMessagesdefaults tofalse. Set it totrueonly if your Telegram client supports Bot API 10.1 rich messages and you want richer markdown rendering; keep it disabled for Telegram Web, which may show unsupported-message errors for rich messages.
3. Run
nanobot gateway
Webhook mode (optional)
Telegram uses long polling by default. To receive updates through a webhook, expose a public HTTPS URL that forwards to nanobot's local listener and set mode to webhook:
{
"channels": {
"telegram": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"mode": "webhook",
"webhookUrl": "https://example.com/telegram",
"webhookListenHost": "127.0.0.1",
"webhookListenPort": 8081,
"webhookPath": "/telegram",
"webhookSecretToken": "CHANGE_ME_RANDOM_SECRET",
"webhookMaxConnections": 4,
"allowFrom": ["YOUR_USER_ID"]
}
}
}
webhookSecretTokenis required in webhook mode. Do not expose the local webhook listener directly to the public internet without a reverse proxy or tunnel in front of it. TLS/Host policy is handled by your proxy; nanobot only listens onwebhookListenHost:webhookListenPortand validates Telegram's webhook secret token.webhookMaxConnectionsdefaults to4; nanobot still serializes Telegram updates per conversation before forwarding them to the agent.
webhookUrlis the public HTTPS URL registered with Telegram.webhookPathis the local path nanobot listens on. They often use the same path, but may differ when a reverse proxy or tunnel rewrites the request path.
Mochat (Claw IM)
Uses Socket.IO WebSocket by default, with HTTP polling fallback.
Install the optional realtime dependency
nanobot plugins enable mochat
Without these dependencies, Mochat still works through HTTP polling.
1. Ask nanobot to set up Mochat for you
Simply send this message to nanobot (replace xxx@xxx with your real email):
Read https://raw.githubusercontent.com/HKUDS/MoChat/refs/heads/main/skills/nanobot/skill.md and register on MoChat. My Email account is xxx@xxx Bind me as your owner and DM me on MoChat.
nanobot will automatically register, configure ~/.nanobot/config.json, and connect to Mochat.
2. Restart gateway
nanobot gateway
That's it — nanobot handles the rest!
Manual configuration (advanced)
If you prefer to configure manually, add the following to ~/.nanobot/config.json:
Keep
claw_tokenprivate. It should only be sent inX-Claw-Tokenheader to your Mochat API endpoint.
{
"channels": {
"mochat": {
"enabled": true,
"base_url": "https://mochat.io",
"socket_url": "https://mochat.io",
"socket_path": "/socket.io",
"claw_token": "claw_xxx",
"agent_user_id": "6982abcdef",
"sessions": ["*"],
"panels": ["*"],
"reply_delay_mode": "non-mention",
"reply_delay_ms": 120000
}
}
}
Discord
1. Create a bot
- Go to https://discord.com/developers/applications
- Create an application → Bot → Add Bot
- Copy the bot token
2. Enable intents
- In the Bot settings, enable MESSAGE CONTENT INTENT
- (Optional) Enable SERVER MEMBERS INTENT if you plan to use allow lists based on member data
3. Get your User ID
- Discord Settings → Advanced → enable Developer Mode
- Right-click your avatar → Copy User ID
4. Configure
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_BOT_TOKEN",
"allowFrom": ["YOUR_USER_ID"],
"allowChannels": [],
"groupPolicy": "mention",
"streaming": true,
"replyToMessage": false
}
}
}
groupPolicycontrols how the bot responds in group channels:
"mention"(default) — Reply only when someone @mentions the bot."open"— Reply to all messages in group channels.- In direct messages, the bot replies only when the sender is listed in
allowFrom.For open group policy, create a private thread and @mention the bot to start a session there. Otherwise, the bot starts a session in both the thread and the channel where you created it.
allowChannelsrestricts the bot to specific Discord channel IDs. The default empty list allows every channel the bot can see. Example:["1234567890", "0987654321"]. TheallowFromandallowChannelsfilters both apply. Threads under an allowed channel are also allowed; for Forum channels, allowing the parent Forum channel allows all its threads and posts.streamingdefaults totrue; disable it only if you want non-streaming replies.replyToMessagedefaults tofalse; enable it to use Discord's native reply UI for responses.
5. Invite the bot
- OAuth2 → URL Generator
- Scopes:
bot - Bot Permissions:
Send Messages,Read Message History - Open the generated invite URL and add the bot to your server
6. Run
nanobot gateway
Matrix (Element)
Enable Matrix support first:
nanobot plugins enable matrix
[!NOTE] Matrix encryption is disabled by default on Windows because
matrix-nio[e2e]depends onpython-olm, which has no pre-built Windows wheel. Use macOS, Linux, or WSL2 if you need Matrix E2EE.
1. Create/choose a Matrix account
- Create or reuse a Matrix account on your homeserver (for example
matrix.org). - Confirm you can log in with Element.
2. Get credentials
- You need:
userId(example:@nanobot:matrix.org)password
(Note: accessToken and deviceId are still supported for legacy reasons, but for reliable encryption, password login is recommended instead. If the password is provided, accessToken and deviceId will be ignored.)
3. Configure
{
"channels": {
"matrix": {
"enabled": true,
"homeserver": "https://matrix.org",
"userId": "@nanobot:matrix.org",
"password": "mypasswordhere",
"e2eeEnabled": true,
"sasVerification": true,
"allowFrom": ["@your_user:matrix.org"],
"groupPolicy": "open",
"groupAllowFrom": [],
"groupPolicyOverrides": {},
"allowRoomMentions": false,
"maxMediaBytes": 20971520
}
}
}
Keep a persistent
matrix-store— encrypted session state is lost if these change across restarts.
| Option | Description |
|---|---|
allowFrom |
User IDs allowed to interact. Empty denies all; use ["*"] to allow everyone. |
groupPolicy |
open (default), mention, allowlist, or listen. |
groupAllowFrom |
Room allowlist (used when policy is allowlist). |
groupPolicyOverrides |
Optional per-room overrides for groupPolicy, keyed by Matrix room ID (for example, "!abc123:matrix.org"). Values mirror groupPolicy: "open", "mention", or "allowlist" (an allowlist override is checked against groupAllowFrom). Rooms not listed fall back to groupPolicy. |
allowRoomMentions |
Accept @room mentions in mention mode. |
replyToMessage |
Quote the user's message in non-threaded replies (default true). Set false to send without quotes; thread replies are unchanged. |
e2eeEnabled |
E2EE support (default true). Set false for plaintext-only. |
sasVerification |
Complete Element-initiated SAS device verification for allowed users (default false). This does not add cross-signing, clear Element's cross-signing trust warning, or let the bot initiate verification. |
maxMediaBytes |
Max attachment size (default 20MB). Set 0 to block all media. |
In listen mode the bot reads every message from allowed senders in the room but replies only when mentioned (same mention semantics as mention, including allowRoomMentions). Unheard messages are kept in a bounded per-room buffer and attached as context to the next mention-triggered reply, so the answer reflects the conversation since its last response. The buffer clears once used, and nothing is ever replied to unheard messages. The buffer is in-memory only — if the bot restarts it starts empty (the bot does not announce the gap). When the buffer cap evicts older messages, the context block notes how many were dropped.
4. Run
nanobot gateway
Requires the WhatsApp optional dependencies:
nanobot plugins enable whatsapp
1. Link device with QR
nanobot channels login whatsapp
# Scan QR with WhatsApp → Settings → Linked Devices
2. Configure
{
"channels": {
"whatsapp": {
"enabled": true,
"allowFrom": ["1234567890"]
}
}
}
For groups, allowFrom can contain either a participant sender ID/LID or a group JID/bare group ID. A participant entry allows that sender wherever the bot can see them; a group entry allows replies in that group.
Optional session database path:
{
"channels": {
"whatsapp": {
"databasePath": "~/.nanobot/whatsapp-auth/neonize.db"
}
}
}
Migrating from the old bridge
- Remove
bridgeUrlandbridgeToken; WhatsApp no longer runs a local Node.js bridge. - Re-run
nanobot channels login whatsapp; old Baileys bridge auth data is not reused by neonize. - Update
allowFromentries to the WhatsApp sender ID without a leading+.
3. Run
nanobot gateway
Optional: static LID mappings
Modern WhatsApp can deliver a sender's LID instead of their phone number. nanobot learns LID to phone mappings at runtime when both identifiers are present, but you can also seed mappings up front so the phone number resolves from the very first message:
{
"channels": {
"whatsapp": {
"enabled": true,
"allowFrom": ["1234567890"],
"lidMappings": { "123456789012345": "1234567890" }
}
}
}
WhatsApp Agent Platform
Connects nanobot through the official WhatsApp Agent Platform API. The agent appears as its own chat in WhatsApp and can only talk to you, its creator. No QR pairing, no linked device, and no optional Python dependencies.
This is a different channel from whatsapp. nanobot is an independent third-party project, not a WhatsApp product. See the WhatsApp Agent Platform guide for the full comparison and walkthrough.
1. Create the agent in WhatsApp
Open WhatsApp → Settings → Agents → Create an agent, then copy the key from the agent's chat → Chat info → API key. This feature is available only in limited countries and might not be in your account yet.
2. Configure
{
"channels": {
"whatsapp_agent": {
"enabled": true,
"token": "${WA_AGENT_TOKEN}"
}
}
}
allowFrom is optional. The platform already restricts the chat to the agent's creator; leave allowFrom empty to require pairing approval instead of a static list.
3. Run
nanobot gateway
Notes
- At most one gateway may poll a given agent token. A second one causes
409and is logged as a duplicate-poller error. - Agent conversations are not end-to-end encrypted. nanobot and your configured model provider process these messages; your other WhatsApp chats are unaffected. Review the third-party agent terms before connecting.
- Replies are split at 4096 characters. Progress and tool-hint messages are off by default because every send spends the same 12-per-minute budget.
- Ambiguous send outcomes (HTTP
500, read timeouts) are not retried by default, because a duplicate is worse than a miss. SetretryAmbiguousSends: trueto opt in.
Feishu
Uses WebSocket long connection — no public IP required.
Quick setup: QR login
nanobot plugins enable feishu
nanobot channels login feishu
# Use --force to create/sign in with a new bot
Open the printed URL or scan the QR code with Feishu/Lark on your phone. If the optional qrcode package is installed, nanobot shows a terminal QR code; otherwise it prints the login URL. nanobot writes appId, appSecret, domain, and enabled under channels.feishu in the active config file. Use --config <path> to update a non-default config.
If QR login is unavailable for your account, use manual setup below.
Manual setup
1. Create a Feishu bot
- Visit Feishu Open Platform
- Create a new app → Enable Bot capability
- Permissions:
im:message(send messages) andim:message.p2p_msg:readonly(receive messages)- Streaming replies (default in nanobot): add
cardkit:card:write(often labeled Create and update cards in the Feishu developer console). Required for CardKit entities and streamed assistant text. Older apps may not have it yet — open Permission management, enable the scope, then publish a new app version if the console requires it. - If you cannot add
cardkit:card:write, set"streaming": falseunderchannels.feishu(see below). The bot still works; replies use normal interactive cards without token-by-token streaming.
- Events: Add
im.message.receive_v1(receive messages)- Select Long Connection mode (requires running nanobot first to establish connection)
- Get App ID and App Secret from "Credentials & Basic Info"
- Publish the app
2. Configure
{
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_xxx",
"appSecret": "xxx",
"encryptKey": "",
"verificationToken": "",
"allowFrom": ["ou_YOUR_OPEN_ID"],
"groupPolicy": "mention",
"reactEmoji": "OnIt",
"doneEmoji": "DONE",
"toolHintPrefix": "🔧",
"streaming": true,
"domain": "feishu"
}
}
}
streamingdefaults totrue. Usefalseif your app does not havecardkit:card:write(see permissions above).encryptKeyandverificationTokenare optional for Long Connection mode.allowFrom: Add your open_id (find it in nanobot logs when you message the bot). Use["*"]to allow all users.groupPolicy:"mention"(default — respond only when @mentioned),"open"(respond to all group messages). Private chats always respond.reactEmoji: Emoji for "processing" status (default:OnIt). See available emojis.doneEmoji: Optional emoji for "completed" status (e.g.,DONE,OK,HEART). When set, bot adds this reaction after removingreactEmoji.toolHintPrefix: Prefix for inline tool hints in streaming cards (default:🔧).domain:"feishu"(default) for China (open.feishu.cn),"lark"for international Lark (open.larksuite.com).
3. Run
nanobot gateway
[!TIP] Feishu uses WebSocket to receive messages — no webhook or public IP needed!
QQ (QQ单聊)
Uses botpy SDK with WebSocket — no public IP required. Currently supports private messages only.
Install the optional channel dependency
nanobot plugins enable qq
1. Register & create bot
- Visit QQ Open Platform → Register as a developer (personal or enterprise)
- Create a new bot application
- Go to 开发设置 (Developer Settings) → copy AppID and AppSecret
2. Set up sandbox for testing
- In the bot management console, find 沙箱配置 (Sandbox Config)
- Under 在消息列表配置, click 添加成员 and add your own QQ number
- Once added, scan the bot's QR code with mobile QQ → open the bot profile → tap "发消息" to start chatting
3. Configure
Run the QR login and scan with mobile QQ to save the AppID and AppSecret automatically. Scanning again replaces the App Secret and stops the previous secret from working:
nanobot channels login qq
To enter them yourself, copy AppID and AppSecret from 开发设置 (Developer Settings) into channels.qq:
allowFrom: Add your openid (find it in nanobot logs when you message the bot). Use["*"]for public access.msgFormat: Optional. Use"plain"(default) for maximum compatibility with legacy QQ clients, or"markdown"for richer formatting on newer clients.- For production: submit a review in the bot console and publish. See QQ Bot Docs for the full publishing flow.
{
"channels": {
"qq": {
"enabled": true,
"appId": "YOUR_APP_ID",
"secret": "YOUR_APP_SECRET",
"allowFrom": ["YOUR_OPENID"],
"msgFormat": "plain"
}
}
}
4. Run
nanobot gateway
Now send a message to the bot from QQ — it should respond!
Napcat (QQ via OneBot v11 支持群聊等功能)
Connects to a Napcat instance over its forward WebSocket (OneBot v11). Use this when you have your own QQ account running through Napcat and want full private + group chat support.
1. Set up Napcat
- Install and log into Napcat, then enable a Forward WebSocket server. See the official Napcat Docker tutorial.
- In the webui, follow "网络配置" -> "新建" -> "Websocket 服务器" to create a forward websocket server. By default, the URL is
ws://127.0.0.1:3001 - Copy the forward websocket server's token
- (Optional) In the webui, follow "系统配置" -> "登陆配置" -> "快速登录QQ" to automatically login after restarts
Install the optional channel dependency
nanobot plugins enable napcat
2. Configure
{
"channels": {
"napcat": {
"enabled": true,
"wsUrl": "ws://127.0.0.1:3001",
"accessToken": "YOUR_WEBSOCKET_TOKEN",
"allowFrom": ["*"],
"groupPolicy": "mention",
"groupPolicyOverrides": {
"123456789": "open",
"987654321": 0.2
},
"welcomeNewMembers": true
}
}
}
| Option | What it does |
|---|---|
wsUrl |
Napcat forward-WebSocket endpoint. Bearer auth via accessToken is sent in the Authorization header. |
allowFrom |
QQ numbers permitted to talk to the bot. ["*"] = anyone. Required ["*"] (or include the joining user) for welcomeNewMembers to fire. |
groupPolicy |
"mention" (default) — reply only when @-mentioned or replying to the bot's own message. "open" — reply to every group message. A float p in [0.0, 1.0] — @mentions and replies-to-bot always reply; every other group message replies with probability p (so 0.0 ≡ "mention", 1.0 ≡ "open"). Private chats always reply. |
groupPolicyOverrides |
Optional per-group overrides for groupPolicy, keyed by group id (as a string). Each value takes the same shape as groupPolicy ("mention", "open", or a float). Groups not listed fall back to groupPolicy. |
welcomeNewMembers |
When true, notice.group_increase events are pushed to the bus as a synthetic message so the agent can greet new joiners. |
maxImageBytes |
Hard cap (in bytes) for inbound image downloads. Defaults to 20 MB. Larger images are dropped with a warning. |
DingTalk (钉钉)
Uses Stream Mode — no public IP required.
Install the optional channel dependency
nanobot plugins enable dingtalk
1. Create a DingTalk bot
- Visit DingTalk Open Platform
- Create a new app -> Add Robot capability
- Configuration:
- Toggle Stream Mode ON
- Permissions: Add necessary permissions for sending messages
- Get AppKey (Client ID) and AppSecret (Client Secret) from "Credentials"
- Publish the app
2. Configure
{
"channels": {
"dingtalk": {
"enabled": true,
"clientId": "YOUR_APP_KEY",
"clientSecret": "YOUR_APP_SECRET",
"allowFrom": ["YOUR_STAFF_ID"],
"groupUserIsolation": false
}
}
}
allowFrom: Add your staff ID. Use["*"]to allow all users.
groupUserIsolation: Optional. Defaults tofalse, which keeps one shared session per group chat. Set it totrueto give each sender in a DingTalk group chat a separate session while replies still go back to the same group.
3. Run
nanobot gateway
Slack
Uses Socket Mode — no public URL required.
Install the optional channel dependency
nanobot plugins enable slack
1. Create a Slack app
- Go to Slack API → Create New App → "From scratch"
- Pick a name and select your workspace
2. Configure the app
- Socket Mode: Toggle ON → Generate an App-Level Token with
connections:writescope → copy it (xapp-...) - OAuth & Permissions: Add bot scopes:
chat:write,reactions:write,app_mentions:read,files:read,files:write,channels:history,groups:history,im:history,mpim:history - Event Subscriptions: Toggle ON → Subscribe to bot events:
message.im,message.channels,app_mention→ Save Changes - App Home: Scroll to Show Tabs → Enable Messages Tab → Check "Allow users to send Slash commands and messages from the messages tab"
- Install App: Click Install to Workspace → Authorize → copy the Bot Token (
xoxb-...)
files:readis required to read files users send to nanobot.files:writeis required for nanobot to send images, videos, and other file uploads. If you add either scope later, reinstall the Slack app to the workspace and restart nanobot so it uses the updated bot token.
3. Configure nanobot
{
"channels": {
"slack": {
"enabled": true,
"botToken": "xoxb-...",
"appToken": "xapp-...",
"dm": {
"policy": "allowlist",
"allowFrom": ["YOUR_SLACK_USER_ID"]
},
"groupPolicy": "mention"
}
}
}
4. Run
nanobot gateway
The listed Slack user can DM the bot directly. Other DM senders receive a pairing code. Group access is independent: with groupPolicy: "mention", any member can invoke the bot by mentioning it in a channel it can see. For DM-only access, set groupPolicy to "allowlist" and leave groupAllowFrom empty.
[!TIP]
groupPolicy:"mention"(default — respond only when @mentioned),"open"(respond to all channel messages), or"allowlist"(restrict to specific channels viagroupAllowFrom).groupAllowFrom: channel IDs the bot may respond in whengroupPolicyis"allowlist".groupRequireMention: whentrueandgroupPolicyis"allowlist", the bot only replies to channels ingroupAllowFromand only when @mentioned (instead of every message). No effect for"mention"/"open". Use this to scope the bot to approved channels while keeping mention-only behavior.- DM policy defaults to open. Set
"dm": {"enabled": false}to disable DMs.
Give nanobot its own email account. It polls IMAP for incoming mail and replies via SMTP — like a personal email assistant.
1. Get credentials (Gmail example)
- Create a dedicated Gmail account for your bot (e.g.
[email protected]) - Enable 2-Step Verification → Create an App Password
- Use this app password for both IMAP and SMTP
2. Configure
consentGrantedmust betrueto allow mailbox access. This is a safety gate — setfalseto fully disable.allowFrom: Add your email address. Use["*"]to accept emails from anyone.trustedAuthservIds: Exactauthserv-idvalues added by the receiving mail service. Required whileverifyDkimorverifySpfis enabled. Gmail normally usesmx.google.com; inspect a received message's raw headers for other services. The service must prepend one consolidated result and remove inbound headers that claim the same identity; duplicate trusted results are rejected. Existing installations must follow the v0.3.5 upgrade instructions before re-enabling verified email polling.smtpUseTlsandsmtpUseSsldefault totrue/falserespectively, which is correct for Gmail (port 587 + STARTTLS). No need to set them explicitly.- Set
"autoReplyEnabled": falseif you only want to read/analyze emails without sending automatic replies.postAction: Optional post-processing for processed emails:"delete"or"move"(defaultnull). This runs only after an accepted email is successfully delivered to the AI pipeline.postActionMoveMailbox: Destination mailbox used whenpostActionis"move"(for example"Processed"or"[Gmail]/Trash").postActionIgnoreSkipped: Iftrue(default), skipped emails are ignored for post-action and not moved/deleted.postActionExpunge: Whentrue, the channel allows a full-mailboxEXPUNGEfallback if UID-scoped expunge is unavailable or fails (defaultfalse). Enable only on very old IMAP servers that lack modern UIDPLUS support. Note that this fallback will expunge all messages marked as deleted in the mailbox, including ones not handled by the agent. Leaving this off is safe for all modern IMAP servers.allowedAttachmentTypes: Save inbound attachments matching these MIME types —["*"]for all, e.g.["application/pdf", "image/*"](default[]= disabled).maxAttachmentSize: Max size per attachment in bytes (default2000000/ 2MB).maxAttachmentsPerEmail: Max attachments to save per email (default5).
{
"channels": {
"email": {
"enabled": true,
"consentGranted": true,
"imapHost": "imap.gmail.com",
"imapPort": 993,
"imapUsername": "[email protected]",
"imapPassword": "your-app-password",
"smtpHost": "smtp.gmail.com",
"smtpPort": 587,
"smtpUsername": "[email protected]",
"smtpPassword": "your-app-password",
"fromAddress": "[email protected]",
"allowFrom": ["[email protected]"],
"trustedAuthservIds": ["mx.google.com"],
"postAction": "move",
"postActionMoveMailbox": "[Gmail]/Trash",
"postActionIgnoreSkipped": true,
"postActionExpunge": false,
"allowedAttachmentTypes": ["application/pdf", "image/*"]
}
}
}
3. Run
nanobot gateway
WeChat (微信 / Weixin)
Uses HTTP long-poll with QR-code login via the ilinkai personal WeChat API. No local WeChat desktop client is required.
1. Enable WeChat support
nanobot plugins enable weixin
2. Configure
{
"channels": {
"weixin": {
"enabled": true,
"allowFrom": ["YOUR_WECHAT_USER_ID"]
}
}
}
allowFrom: Add the sender ID you see in nanobot logs for your WeChat account. Use["*"]to allow all users.token: Optional. If omitted, log in interactively and nanobot will save the token for you.routeTag: Optional. When your upstream Weixin deployment requires request routing, nanobot will send it as theSKRouteTagheader.stateDir: Optional. Defaults to nanobot's runtime directory for Weixin state.pollTimeout: Optional long-poll timeout in seconds.
3. Login
nanobot channels login weixin
Use --force to re-authenticate and ignore any saved token:
nanobot channels login weixin --force
4. Run
nanobot gateway
Wecom (企业微信)
Here we use wecom-aibot-sdk-python (community Python version of the official @wecom/aibot-node-sdk).
Uses WebSocket long connection — no public IP required.
1. Enable WeCom support
nanobot plugins enable wecom
2. Create a WeCom AI Bot
Go to the WeCom admin console → Intelligent Robot → Create Robot → select API mode with long connection. Copy the Bot ID and Secret.
3. Configure
{
"channels": {
"wecom": {
"enabled": true,
"botId": "your_bot_id",
"secret": "your_bot_secret",
"allowFrom": ["your_id"]
}
}
}
4. Run
nanobot gateway
Microsoft Teams (MVP — DM only)
Direct-message text in/out, tenant-aware OAuth, conversation reference persistence. Uses a public HTTPS webhook — no WebSocket; you need a tunnel or reverse proxy.
1. Enable Microsoft Teams support
nanobot plugins enable msteams
2. Create a Teams / Azure bot app registration
Create or reuse a Microsoft Teams / Azure bot app registration. Set the bot messaging endpoint to a public HTTPS URL ending in /api/messages.
3. Configure
{
"channels": {
"msteams": {
"enabled": true,
"appId": "YOUR_APP_ID",
"appPassword": "YOUR_APP_SECRET",
"tenantId": "YOUR_TENANT_ID",
"host": "0.0.0.0",
"port": 3978,
"path": "/api/messages",
"allowFrom": ["*"],
"replyInThread": true,
"mentionOnlyResponse": "Hi — what can I help with?",
"validateInboundAuth": true,
"refTtlDays": 30,
"pruneWebChatRefs": true,
"pruneNonPersonalRefs": true,
"refTouchIntervalS": 300
}
}
}
replyInThread: truereplies to the triggering Teams activity when a storedactivity_idis available.mentionOnlyResponsecontrols what Nanobot receives when a user sends only a bot mention (<at>Nanobot</at>). Set to""to ignore mention-only messages.validateInboundAuth: trueenables inbound Bot Framework bearer-token validation (signature, issuer, audience, lifetime,serviceUrl). This is the safe default for public deployments. Only set it tofalsefor local development or tightly controlled testing.refTtlDays(default30) controls how old stored conversation refs can be before they are pruned.pruneWebChatRefs(defaulttrue) drops refs withwebchat.botframework.comservice URLs.pruneNonPersonalRefs(defaulttrue) drops refs whoseconversation_typeis notpersonal.refTouchIntervalS(default300) throttles how often successful sends refreshupdated_atfor active refs.
4. Run
nanobot gateway
Signal
Uses signal-cli daemon in HTTP mode — receive messages via SSE, send via JSON-RPC.
1. Install signal-cli
Install signal-cli and register a phone number:
signal-cli -u +1234567890 register
signal-cli -u +1234567890 verify <CODE>
Start the daemon:
signal-cli -a +1234567890 daemon --http localhost:8080
2. Configure
{
"channels": {
"signal": {
"enabled": true,
"phoneNumber": "+1234567890",
"daemonHost": "localhost",
"daemonPort": 8080,
"dm": {
"enabled": true,
"policy": "open"
},
"group": {
"enabled": true,
"policy": "open",
"requireMention": true
}
}
}
}
phoneNumber: Your registered Signal phone number.daemonHost/daemonPort: Where signal-cli daemon is listening (defaultlocalhost:8080).dm.policy:"open"(anyone can DM) or"allowlist"(only listed numbers/UUIDs). When"allowlist", unlisted DM senders receive a pairing code.dm.allowFrom: List of allowed phone numbers or UUIDs (used when policy is"allowlist").group.policy:"open"(all groups) or"allowlist"(only listed group IDs).group.requireMention: Whentrue(default), the bot only responds in groups when @mentioned.group.allowFrom: List of allowed group IDs (used when group policy is"allowlist").attachmentsDir: Override the directory where signal-cli stores inbound attachments. Defaults to~/.local/share/signal-cli/attachments(the Linux default). Set this if signal-cli runs with a customXDG_DATA_HOMEor on macOS/Windows.groupMessageBufferSize: Number of recent group messages kept for context (default20, must be > 0).
3. Run
nanobot gateway
[!TIP] The channel automatically reconnects to the signal-cli daemon with exponential backoff if the connection drops. Markdown in bot replies is automatically converted to Signal text styles (bold, italic, code, etc.).