nanobot/docs/chat-apps.md

Chat Apps

Connect nanobot to your favorite chat platform. Want to build your own? See the Channel Plugin Guide.

Channel	What you need
Telegram	Bot token from @BotFather
Discord	Bot token + Message Content intent
WhatsApp	QR code scan (nanobot channels login whatsapp)
WeChat (Weixin)	QR code scan (nanobot channels login weixin)
Feishu	App ID + App Secret
DingTalk	App Key + App Secret
Slack	Bot token + App-Level token
Matrix	Homeserver URL + Access token
Email	IMAP/SMTP credentials
QQ	App ID + App Secret
Wecom	Bot ID + Bot Secret
Microsoft Teams	App ID + App Password + public HTTPS endpoint
Mochat	Claw token (auto-setup available)

Telegram (Recommended)

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

Mochat (Claw IM)

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!

Manual configuration (advanced)

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

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

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

Matrix (Element)

Install Matrix dependencies first:

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,
      "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.

Option	Description
allowFrom	User IDs allowed to interact. Empty denies all; use ["*"] to allow everyone.
groupPolicy	open (default), mention, or allowlist.
groupAllowFrom	Room allowlist (used when policy is allowlist).
allowRoomMentions	Accept @room mentions in mention mode.
e2eeEnabled	E2EE support (default true). Set false for plaintext-only.
maxMediaBytes	Max attachment size (default 20MB). Set 0 to block all media.

4. Run

nanobot gateway

WhatsApp

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

Feishu

Uses WebSocket long connection — no public IP required.

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!

QQ (QQ单聊)

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!

DingTalk (钉钉)

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

allowFrom: Add your staff ID. Use ["*"] to allow all users.

3. Run

nanobot gateway

Slack

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, 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-...)

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).
• DM policy defaults to open. Set "dm": {"enabled": false} to disable DMs.

Email

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. my-nanobot@gmail.com)
• 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.
• 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": "my-nanobot@gmail.com",
      "imapPassword": "your-app-password",
      "smtpHost": "smtp.gmail.com",
      "smtpPort": 587,
      "smtpUsername": "my-nanobot@gmail.com",
      "smtpPassword": "your-app-password",
      "fromAddress": "my-nanobot@gmail.com",
      "allowFrom": ["your-real-email@gmail.com"],
      "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. Install with WeChat support

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

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

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

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

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

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

4. Run

nanobot gateway