Chat Apps

Connect nanobot to your favorite chat platform. Want to build your own? See the Channel Plugin 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.

Most examples below are snippets to merge into ~/.nanobot/config.json.

Common Setup Pattern

Every chat app uses the same shape:

1. Create or prepare the bot/account in the chat platform.
2. Copy the token, secret, QR login state, webhook URL, or account ID that platform gives you.
3. Merge that platform's JSON snippet into ~/.nanobot/config.json.
4. Keep access control narrow at first with allowFrom or the platform-specific allow list.
5. Check that nanobot can see the configured channel:

nanobot channels status

6. Start the gateway and leave that terminal running:

nanobot gateway

7. Send a message from the allowed account. In group chats, follow that channel's groupPolicy behavior: 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.

["*"] 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.

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"]
    }
  }
}

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.

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"]
    }
  }
}

webhookSecretToken is 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 on webhookListenHost:webhookListenPort and validates Telegram's webhook secret token. webhookMaxConnections defaults to 4; nanobot still serializes Telegram updates per conversation before forwarding them to the agent.

webhookUrl is the public HTTPS URL registered with Telegram. webhookPath is 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.

Uses Socket.IO WebSocket by default, with HTTP polling fallback.

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!

If you prefer to configure manually, add the following to ~/.nanobot/config.json:

Keep claw_token private. It should only be sent in X-Claw-Token header 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
    }
  }
}

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
    }
  }
}

groupPolicy controls how the bot responds in group channels:

• "mention" (default) — Only respond when @mentioned
• "open" — Respond to all messages DMs always respond when the sender is in allowFrom.
• If you set group policy to open create new threads as private threads and then @ the bot into it. Otherwise the thread itself and the channel in which you spawned it will spawn a bot session. allowChannels restricts the bot to specific Discord channel IDs. Empty (default) means respond in every channel the bot can see. Example: ["1234567890", "0987654321"]. The filter applies after allowFrom, so both must pass. Discord threads under an allowed parent channel are also allowed; for Forum channels, allowing the parent Forum channel allows all threads/posts in that forum. streaming defaults to true. Disable it only if you explicitly want non-streaming replies.

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

Install Matrix dependencies first:

python -m pip install "nanobot-ai[matrix]"

[!NOTE] Matrix is not supported on Windows. matrix-nio[e2e] depends on python-olm, which has no pre-built Windows wheel and is skipped by the matrix extra on sys_platform == 'win32'. The command above will still succeed on Windows but without matrix-nio installed, so enabling the Matrix channel will fail at startup. Use macOS, Linux, or WSL2.

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": [],
      "allowRoomMentions": false,
      "maxMediaBytes": 20971520
    }
  }
}

Keep a persistent matrix-store — encrypted session state is lost if these change across restarts.

4. Run

nanobot gateway

Requires Node.js ≥18.

1. Link device

nanobot channels login whatsapp
# Scan QR with WhatsApp → Settings → Linked Devices

2. Configure

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890"]
    }
  }
}

3. Run (two terminals)

# Terminal 1
nanobot channels login whatsapp

# Terminal 2
nanobot gateway

WhatsApp bridge updates are not applied automatically for existing installations. After upgrading nanobot, rebuild the local bridge with: rm -rf ~/.nanobot/bridge && nanobot channels login whatsapp

Optional: static LID mappings

Modern WhatsApp can deliver a sender's LID instead of their phone number. nanobot learns the LID→phone mapping at runtime (and reuses the ones the bridge persists on disk), 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" }
    }
  }
}

Uses WebSocket long connection — no public IP required.

Quick setup: QR login

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) and im: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": false under channels.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"
    }
  }
}

streaming defaults to true. Use false if your app does not have cardkit:card:write (see permissions above). encryptKey and verificationToken are 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 removing reactEmoji. 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!

Uses botpy SDK with WebSocket — no public IP required. Currently supports private messages only.

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

• 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!

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

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
    }
  }
}

Uses Stream Mode — no public IP required.

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 to false, which keeps one shared session per group chat. Set it to true to give each sender in a DingTalk group chat a separate session while replies still go back to the same group.

3. Run

nanobot gateway

Uses Socket Mode — no public URL required.

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:write scope → 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:read is required to read files users send to nanobot. files:write is 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-...",
      "allowFrom": ["YOUR_SLACK_USER_ID"],
      "groupPolicy": "mention"
    }
  }
}

4. Run

nanobot gateway

DM the bot directly or @mention it in a channel — it should respond!

[!TIP]

• groupPolicy: "mention" (default — respond only when @mentioned), "open" (respond to all channel messages), or "allowlist" (restrict to specific channels via groupAllowFrom).
• groupAllowFrom: channel IDs the bot may respond in when groupPolicy is "allowlist".
• groupRequireMention: when true and groupPolicy is "allowlist", the bot only replies to channels in groupAllowFrom and 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

• consentGranted must be true to allow mailbox access. This is a safety gate — set false to fully disable.
• allowFrom: Add your email address. Use ["*"] to accept emails from anyone.
• smtpUseTls and smtpUseSsl default to true / false respectively, which is correct for Gmail (port 587 + STARTTLS). No need to set them explicitly.
• Set "autoReplyEnabled": false if you only want to read/analyze emails without sending automatic replies.
• postAction: Optional post-processing for processed emails: "delete" or "move" (default null). This runs only after an accepted email is successfully delivered to the AI pipeline.
• postActionMoveMailbox: Destination mailbox used when postAction is "move" (for example "Processed" or "[Gmail]/Trash").
• postActionIgnoreSkipped: If true (default), skipped emails are ignored for post-action and not moved/deleted.
• postActionExpunge: When true, the channel allows a full-mailbox EXPUNGE fallback if UID-scoped expunge is unavailable or fails (default false). 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 (default 2000000 / 2MB).
• maxAttachmentsPerEmail: Max attachments to save per email (default 5).

{
  "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]"],
      "postAction": "move",
      "postActionMoveMailbox": "[Gmail]/Trash",
      "postActionIgnoreSkipped": true,
      "postActionExpunge": false,
      "allowedAttachmentTypes": ["application/pdf", "image/*"]
    }
  }
}

3. Run

nanobot gateway

Uses HTTP long-poll with QR-code login via the ilinkai personal WeChat API. No local WeChat desktop client is required.

1. Install with WeChat support

python -m pip install "nanobot-ai[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 the SKRouteTag header.
• 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

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. Install the optional dependency

python -m pip install "nanobot-ai[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

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. Install the optional dependency

python -m pip install "nanobot-ai[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: true replies to the triggering Teams activity when a stored activity_id is available.
• mentionOnlyResponse controls what Nanobot receives when a user sends only a bot mention (<at>Nanobot</at>). Set to "" to ignore mention-only messages.
• validateInboundAuth: true enables inbound Bot Framework bearer-token validation (signature, issuer, audience, lifetime, serviceUrl). This is the safe default for public deployments. Only set it to false for local development or tightly controlled testing.
• refTtlDays (default 30) controls how old stored conversation refs can be before they are pruned.
• pruneWebChatRefs (default true) drops refs with webchat.botframework.com service URLs.
• pruneNonPersonalRefs (default true) drops refs whose conversation_type is not personal.
• refTouchIntervalS (default 300) throttles how often successful sends refresh updated_at for active refs.

4. Run

nanobot gateway

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 (default localhost: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: When true (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 custom XDG_DATA_HOME or on macOS/Windows.
• groupMessageBufferSize: Number of recent group messages kept for context (default 20, 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.).