Channel Configuration

Overview

Nanobot supports multiple chat platforms through a unified channel configuration system. Each channel can be independently enabled and configured with platform-specific settings.

ChannelsConfig

Root configuration for all chat channels.

sendProgress

bool

default:"true"

Stream agent’s text progress to channels in real-time.

sendToolHints

bool

default:"false"

Stream tool call hints (e.g., read_file("...")) to channels.

WhatsAppConfig

default:"WhatsAppConfig()"

WhatsApp channel configuration.

TelegramConfig

default:"TelegramConfig()"

Telegram channel configuration.

discord

DiscordConfig

default:"DiscordConfig()"

Discord channel configuration.

feishu

FeishuConfig

default:"FeishuConfig()"

Feishu/Lark channel configuration.

mochat

MochatConfig

default:"MochatConfig()"

Mochat channel configuration.

dingtalk

DingTalkConfig

default:"DingTalkConfig()"

DingTalk channel configuration.

EmailConfig

default:"EmailConfig()"

Email channel configuration.

slack

SlackConfig

default:"SlackConfig()"

Slack channel configuration.

QQConfig

default:"QQConfig()"

QQ channel configuration.

matrix

MatrixConfig

default:"MatrixConfig()"

Matrix (Element) channel configuration.

WhatsAppConfig

enabled

bool

default:"false"

Enable WhatsApp channel.

bridgeUrl

str

default:"ws://localhost:3001"

WebSocket URL for WhatsApp bridge connection.

bridgeToken

str

default:""

Shared token for bridge authentication (optional but recommended).

allowFrom

list[str]

default:"[]"

Allowed phone numbers. Empty list allows all.

TelegramConfig

enabled

bool

default:"false"

Enable Telegram channel.

token

str

default:""

Bot token from @BotFather.

allowFrom

list[str]

default:"[]"

Allowed user IDs or usernames. Empty list allows all.

proxy

str | null

default:"null"

HTTP/SOCKS5 proxy URL (e.g., http://127.0.0.1:7890 or socks5://127.0.0.1:1080).

replyToMessage

bool

default:"false"

If true, bot replies quote the original message.

Discord

DiscordConfig

enabled

bool

default:"false"

Enable Discord channel.

token

str

default:""

Bot token from Discord Developer Portal.

allowFrom

list[str]

default:"[]"

Allowed user IDs. Empty list allows all.

gatewayUrl

str

default:"wss://gateway.discord.gg/?v=10&encoding=json"

Discord Gateway WebSocket URL.

intents

int

default:"37377"

Gateway intents (GUILDS + GUILD_MESSAGES + DIRECT_MESSAGES + MESSAGE_CONTENT).

groupPolicy

'mention' | 'open'

default:"mention"

Group chat behavior: mention (respond only when mentioned) or open (respond to all).

Feishu/Lark

FeishuConfig

Feishu (Lark) configuration using WebSocket long connection.

enabled

bool

default:"false"

Enable Feishu/Lark channel.

appId

str

default:""

App ID from Feishu Open Platform.

appSecret

str

default:""

App Secret from Feishu Open Platform.

encryptKey

str

default:""

Encrypt Key for event subscription (optional).

verificationToken

str

default:""

Verification Token for event subscription (optional).

allowFrom

list[str]

default:"[]"

Allowed user open_ids. Empty list allows all.

reactEmoji

str

default:"THUMBSUP"

Emoji type for message reactions (e.g., THUMBSUP, OK, DONE, SMILE).

DingTalk

DingTalkConfig

DingTalk configuration using Stream mode.

enabled

bool

default:"false"

Enable DingTalk channel.

clientId

str

default:""

AppKey from DingTalk Open Platform.

clientSecret

str

default:""

AppSecret from DingTalk Open Platform.

allowFrom

list[str]

default:"[]"

Allowed staff_ids. Empty list allows all.

Email

EmailConfig

Email channel with IMAP (inbound) and SMTP (outbound).

enabled

bool

default:"false"

Enable Email channel.

Explicit permission to access mailbox data (required for privacy compliance).

IMAP (Receive)

imapHost

str

default:""

IMAP server hostname.

imapPort

int

default:"993"

IMAP server port.

imapUsername

str

default:""

IMAP username.

imapPassword

str

default:""

IMAP password.

imapMailbox

str

default:"INBOX"

IMAP mailbox to monitor.

imapUseSsl

bool

default:"true"

Use SSL for IMAP connection.

SMTP (Send)

smtpHost

str

default:""

SMTP server hostname.

smtpPort

int

default:"587"

SMTP server port.

smtpUsername

str

default:""

SMTP username.

smtpPassword

str

default:""

SMTP password.

smtpUseTls

bool

default:"true"

Use TLS for SMTP connection.

smtpUseSsl

bool

default:"false"

Use SSL for SMTP connection (mutually exclusive with TLS).

fromAddress

str

default:""

Email address to send from.

Behavior

autoReplyEnabled

bool

default:"true"

If false, inbound emails are read but no automatic reply is sent.

pollIntervalSeconds

int

default:"30"

Polling interval for checking new emails.

markSeen

bool

default:"true"

Mark emails as seen after reading.

maxBodyChars

int

default:"12000"

Maximum email body length to process.

subjectPrefix

str

default:"Re: "

Prefix for reply email subjects.

allowFrom

list[str]

default:"[]"

Allowed sender email addresses. Empty list allows all.

Slack

SlackConfig

enabled

bool

default:"false"

Enable Slack channel.

mode

str

default:"socket"

Connection mode (currently only socket supported).

webhookPath

str

default:"/slack/events"

Webhook endpoint path.

botToken

str

default:""

Bot token (starts with xoxb-).

appToken

str

default:""

App-level token (starts with xapp-).

userTokenReadOnly

bool

default:"true"

Limit user token to read-only operations.

replyInThread

bool

default:"true"

Reply in threads instead of channel.

reactEmoji

str

default:"eyes"

Emoji for message reactions (without colons).

allowFrom

list[str]

default:"[]"

Allowed Slack user IDs (sender-level). Empty list allows all.

groupPolicy

str

default:"mention"

Group behavior: mention, open, or allowlist.

groupAllowFrom

list[str]

default:"[]"

Allowed channel IDs when using allowlist policy.

SlackDMConfig

default:"SlackDMConfig()"

Direct message policy configuration.

SlackDMConfig

enabled

bool

default:"true"

Enable direct messages.

policy

str

default:"open"

DM policy: open or allowlist.

allowFrom

list[str]

default:"[]"

Allowed Slack user IDs for DMs when using allowlist policy.

Mochat

MochatConfig

Mochat (WeChat enterprise integration) configuration.

enabled

bool

default:"false"

Enable Mochat channel.

baseUrl

str

default:"https://mochat.io"

Mochat base URL.

socketUrl

str

default:""

Socket.io server URL (defaults to baseUrl if empty).

socketPath

str

default:"/socket.io"

Socket.io path.

socketDisableMsgpack

bool

default:"false"

Disable MessagePack parser.

socketReconnectDelayMs

int

default:"1000"

Initial reconnect delay in milliseconds.

socketMaxReconnectDelayMs

int

default:"10000"

Maximum reconnect delay in milliseconds.

socketConnectTimeoutMs

int

default:"10000"

Connection timeout in milliseconds.

refreshIntervalMs

int

default:"30000"

Refresh interval in milliseconds.

watchTimeoutMs

int

default:"25000"

Watch timeout in milliseconds.

watchLimit

int

default:"100"

Maximum number of watched items.

retryDelayMs

int

default:"500"

Retry delay in milliseconds.

maxRetryAttempts

int

default:"0"

Maximum retry attempts (0 = unlimited).

clawToken

str

default:""

Claw authentication token.

agentUserId

str

default:""

Agent user ID.

sessions

list[str]

default:"[]"

Session IDs to monitor.

panels

list[str]

default:"[]"

Panel IDs to monitor.

allowFrom

list[str]

default:"[]"

Allowed user IDs. Empty list allows all.

mention

MochatMentionConfig

default:"MochatMentionConfig()"

Mention behavior configuration.

groups

dict[str, MochatGroupRule]

default:"{}"

Per-group mention rules.

replyDelayMode

str

default:"non-mention"

Reply delay mode: off or non-mention.

replyDelayMs

int

default:"120000"

Reply delay in milliseconds (default: 2 minutes).

MochatMentionConfig

requireInGroups

bool

default:"false"

Require mention in group chats.

MochatGroupRule

requireMention

bool

default:"false"

Require mention for this specific group.

QQ

QQConfig

QQ channel using botpy SDK.

enabled

bool

default:"false"

Enable QQ channel.

appId

str

default:""

Robot ID (AppID) from q.qq.com.

secret

str

default:""

Robot secret (AppSecret) from q.qq.com.

allowFrom

list[str]

default:"[]"

Allowed user openids. Empty list = public access.

Matrix

MatrixConfig

Matrix (Element) protocol configuration.

enabled

bool

default:"false"

Enable Matrix channel.

homeserver

str

default:"https://matrix.org"

Matrix homeserver URL.

accessToken

str

default:""

Access token for bot authentication.

userId

str

default:""

Bot user ID (e.g., @bot:matrix.org).

deviceId

str

default:""

Device ID for this bot instance.

e2eeEnabled

bool

default:"true"

Enable end-to-end encryption support.

syncStopGraceSeconds

int

default:"2"

Graceful shutdown timeout for sync_forever.

maxMediaBytes

int

default:"20971520"

Maximum attachment size (20MB default).

allowFrom

list[str]

default:"[]"

Allowed user IDs. Empty list allows all.

groupPolicy

'open' | 'mention' | 'allowlist'

default:"open"

Group chat behavior: open, mention, or allowlist.

groupAllowFrom

list[str]

default:"[]"

Allowed room IDs when using allowlist policy.

allowRoomMentions

bool

default:"false"

Allow @room mentions to trigger responses.

Configuration Examples

Basic Telegram Setup

channels:
  telegram:
    enabled: true
    token: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
    allowFrom:
      - "@username"
      - "123456789"

Discord with Group Policy

channels:
  discord:
    enabled: true
    token: "your-bot-token"
    groupPolicy: mention  # Only respond when mentioned
    allowFrom:
      - "987654321098765432"  # User ID

Email with Gmail

channels:
  email:
    enabled: true
    consentGranted: true  # Required for privacy
    
    # IMAP
    imapHost: imap.gmail.com
    imapPort: 993
    imapUsername: [email protected]
    imapPassword: ${GMAIL_APP_PASSWORD}
    imapUseSsl: true
    
    # SMTP
    smtpHost: smtp.gmail.com
    smtpPort: 587
    smtpUsername: [email protected]
    smtpPassword: ${GMAIL_APP_PASSWORD}
    smtpUseTls: true
    fromAddress: [email protected]
    
    # Behavior
    pollIntervalSeconds: 60
    allowFrom:
      - "[email protected]"

Slack with Threading

channels:
  slack:
    enabled: true
    mode: socket
    botToken: xoxb-your-bot-token
    appToken: xapp-your-app-token
    replyInThread: true
    reactEmoji: eyes
    groupPolicy: mention
    dm:
      enabled: true
      policy: open

Matrix with E2EE

channels:
  matrix:
    enabled: true
    homeserver: https://matrix.example.com
    accessToken: ${MATRIX_ACCESS_TOKEN}
    userId: "@nanobot:matrix.example.com"
    deviceId: NANOBOT_DEVICE
    e2eeEnabled: true
    groupPolicy: mention
    allowRoomMentions: false

Multiple Channels

channels:
  sendProgress: true
  sendToolHints: false
  
  telegram:
    enabled: true
    token: ${TELEGRAM_TOKEN}
  
  discord:
    enabled: true
    token: ${DISCORD_TOKEN}
    groupPolicy: mention
  
  slack:
    enabled: true
    botToken: ${SLACK_BOT_TOKEN}
    appToken: ${SLACK_APP_TOKEN}

Access Control

All channels support allowFrom for access control:

Empty list: Allow all users (public access)
With entries: Only allow specified users

Examples

# Public access
allowFrom: []

# Restrict to specific users
allowFrom:
  - "[email protected]"
  - "[email protected]"
  - "123456789"  # User ID

Group Policies

Channels with group chat support offer different policies:

open: Respond to all messages in groups
mention: Only respond when bot is mentioned
allowlist: Only respond in whitelisted channels/rooms

groupPolicy: mention
groupAllowFrom:
  - "C1234567890"  # Slack channel ID
  - "!room:matrix.org"  # Matrix room ID

CLI Commands

Agent API

Tools

Configuration Schema

​Overview

​ChannelsConfig

​WhatsApp

​WhatsAppConfig

​Telegram

​TelegramConfig

​Discord

​DiscordConfig

​Feishu/Lark

​FeishuConfig

​DingTalk

​DingTalkConfig

​Email

​EmailConfig

​IMAP (Receive)

​SMTP (Send)

​Behavior

​Slack

​SlackConfig

​SlackDMConfig

​Mochat

​MochatConfig

​MochatMentionConfig

​MochatGroupRule

​QQ

​QQConfig

​Matrix

​MatrixConfig

​Configuration Examples

​Basic Telegram Setup

​Discord with Group Policy

​Email with Gmail

​Slack with Threading

​Matrix with E2EE

​Multiple Channels

​Access Control

​Examples

​Group Policies

Build docs developers (and LLMs) love

Overview

ChannelsConfig

WhatsApp

WhatsAppConfig

Telegram

TelegramConfig

Discord

DiscordConfig

Feishu/Lark

FeishuConfig

DingTalk

DingTalkConfig

Email

EmailConfig

IMAP (Receive)

SMTP (Send)

Behavior

Slack

SlackConfig

SlackDMConfig

Mochat

MochatConfig

MochatMentionConfig

MochatGroupRule

QQ

QQConfig

Matrix

MatrixConfig

Configuration Examples

Basic Telegram Setup

Discord with Group Policy

Email with Gmail

Slack with Threading

Matrix with E2EE

Multiple Channels

Access Control

Examples

Group Policies