channels - nanobot

Usage

nanobot channels [COMMAND] [OPTIONS]

Description

The channels command group manages connections to external chat platforms:

WhatsApp
Telegram
Discord
Slack
Email
DingTalk
Feishu (Lark)
QQ
Mochat

Use these commands to check channel status and authenticate with WhatsApp via QR code.

Subcommands

status

Show the configuration status of all channels.

nanobot channels status

Authenticate WhatsApp by scanning a QR code.

nanobot channels login

channels status

Display a table showing which channels are enabled and their configuration state.

Usage

nanobot channels status

Example Output

           Channel Status           
┏━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Channel   ┃ Enabled ┃ Configuration           ┃
┡━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ WhatsApp  │ ✓       │ ws://localhost:3001     │
│ Discord   │ ✓       │ wss://gateway.discord…  │
│ Feishu    │ ✗       │ not configured          │
│ Mochat    │ ✗       │ not configured          │
│ Telegram  │ ✓       │ token: 123456789:A...   │
│ Slack     │ ✗       │ not configured          │
│ DingTalk  │ ✗       │ not configured          │
│ QQ        │ ✗       │ not configured          │
│ Email     │ ✗       │ not configured          │
└───────────┴─────────┴─────────────────────────┘

Column Descriptions

Channel

string

The name of the chat platform.

Enabled

boolean

Whether the channel is enabled in config.json:

✓: Enabled
✗: Disabled

Configuration

string

Channel-specific configuration details:

API tokens: Truncated token preview (first 10 chars)
URLs: Bridge/gateway endpoints
not configured: Missing required credentials

Configuration Details by Channel

Shows bridge URL:

WhatsApp  │ ✓  │ ws://localhost:3001

Shows truncated bot token:

Telegram  │ ✓  │ token: 123456789:A...

Discord

Shows gateway URL:

Discord   │ ✓  │ wss://gateway.discord.gg/...

Slack

Shows connection mode:

Slack     │ ✓  │ socket

Feishu (Lark)

Shows app_id:

Feishu    │ ✓  │ app_id: cli_a12345...

DingTalk

Shows client_id:

DingTalk  │ ✓  │ client_id: dinga12345...

QQ

Shows app_id:

QQ        │ ✓  │ app_id: 102012345...

Email

Shows IMAP host:

Email     │ ✓  │ imap.gmail.com

Mochat

Shows base URL:

Mochat    │ ✓  │ http://mochat.example.com

Not Configured State

When a channel is enabled but missing credentials:

Telegram  │ ✓  │ not configured

This means enabled: true in config but token/credentials are empty. Authenticate WhatsApp by scanning a QR code with your phone.

Usage

nanobot channels login

Requirements

Node.js: Version 18 or higher
npm: Package manager

First Run

On first run, nanobot will:

Install the WhatsApp bridge
Build the bridge
Start the authentication flow

nanobot channels login

Output:

🐈 Setting up bridge...
  Installing dependencies...
  Building...
[green]✓[/green] Bridge ready

🐈 Starting bridge...
Scan the QR code to connect.

█████████████████████████████
█████████████████████████████
███ ▄▄▄▄▄ █▀  █▀▀█ ▄▄▄▄▄ ███
███ █   █ █▀▄ ▀ ▄█ █   █ ███
███ █▄▄▄█ █ ▀▀█▄ █ █▄▄▄█ ███
███▄▄▄▄▄▄▄█ ▀ ▀ █▄▄▄▄▄▄▄███
...

Scanning QR Code

Open WhatsApp on your phone
Go to Settings → Linked Devices
Tap Link a Device
Scan the QR code displayed in your terminal

After successful scan:

✓ Connected as: Your Name (+1234567890)

Subsequent Runs

Once authenticated, the session persists:

nanobot channels login

Output:

🐈 Starting bridge...
✓ Restored session: Your Name (+1234567890)

The bridge stays connected until you:

Close the terminal
Log out from WhatsApp settings
Delete session: rm -rf ~/.nanobot/bridge/.wwebjs_auth/

Bridge Directory

Bridge is installed to: ~/.nanobot/bridge/

~/.nanobot/bridge/
├── dist/              # Built JavaScript
├── src/               # TypeScript source
├── node_modules/      # Dependencies
├── .wwebjs_auth/      # WhatsApp session
├── package.json
└── tsconfig.json

Bridge Token

Optionally secure the bridge with a token:

{
  "channels": {
    "whatsapp": {
      "bridge_token": "your-secret-token"
    }
  }
}

Or via environment:

BRIDGE_TOKEN=your-secret-token nanobot channels login

Keep Bridge Running

For persistent WhatsApp connection, run the gateway:

nanobot gateway

This starts the bridge automatically if WhatsApp is enabled.

Configuration

Channels are configured in ~/.nanobot/config.json:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "bridge_url": "ws://localhost:3001",
      "bridge_token": "",
      "allow_from": []
    },
    "telegram": {
      "enabled": false,
      "token": "",
      "allow_from": [],
      "proxy": null
    },
    "discord": {
      "enabled": false,
      "token": "",
      "allow_from": []
    },
    "slack": {
      "enabled": false,
      "app_token": "",
      "bot_token": ""
    },
    "email": {
      "enabled": false,
      "imap_host": "",
      "imap_port": 993,
      "smtp_host": "",
      "smtp_port": 587,
      "username": "",
      "password": ""
    }
  }
}

See Channel Configuration for all options.

Troubleshooting

npm Not Found

[red]npm not found. Please install Node.js >= 18.[/red]

Solution:

# macOS
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version
npm --version

Bridge Build Failed

[red]Build failed: Error...[/red]

Solution:

# Clean and rebuild
rm -rf ~/.nanobot/bridge/
nanobot channels login

QR Code Not Showing

Solution: Ensure your terminal supports UTF-8:

echo $LANG  # Should be *.UTF-8
export LANG=en_US.UTF-8

WhatsApp Session Expired

✗ Session expired, please re-authenticate

Solution:

# Remove old session
rm -rf ~/.nanobot/bridge/.wwebjs_auth/

# Re-authenticate
nanobot channels login

Bridge Connection Lost

✗ Disconnected from WhatsApp

Solution: The bridge may have crashed. Restart:

nanobot channels login

Gateway Not Routing Messages

If channels show as enabled but messages don’t work:

# Check gateway is running
nanobot gateway --verbose

# Check channel status
nanobot channels status

Ensure:

Channel is enabled in config
Credentials are valid
Gateway service is running
No firewall blocking connections

Running Multiple Channels

Enable multiple channels simultaneously:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123:ABC"
    },
    "discord": {
      "enabled": true,
      "token": "xyz.abc.123"
    },
    "whatsapp": {
      "enabled": true
    }
  }
}

Start gateway:

nanobot gateway

Output:

[green]✓[/green] Channels enabled: telegram, discord, whatsapp

Security

Access Control

Restrict who can message the bot using allow_from:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123:ABC",
      "allow_from": ["@username1", "123456789"]
    },
    "whatsapp": {
      "enabled": true,
      "allow_from": ["+1234567890", "+9876543210"]
    }
  }
}

Empty list = allow everyone (default).

Bridge Token

Secure the WhatsApp bridge:

{
  "channels": {
    "whatsapp": {
      "bridge_token": "your-random-secret-token-here"
    }
  }
}

Generate a secure token:

openssl rand -hex 32

Credentials

Never commit config.json to git if it contains tokens/passwords. Use environment variables:

export TELEGRAM_TOKEN="123:ABC"
export DISCORD_TOKEN="xyz.abc.123"

Or use a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.).

Exit Codes

0: Success
1: Error (npm missing, build failed, connection error)
130: Interrupted by user (Ctrl+C)

gateway - Start channel gateway
status - Check overall configuration
onboard - Initialize configuration

CLI Commands

Agent API

Tools

Configuration Schema

​Usage

​Description

​Subcommands

​status

​login

​channels status

​Usage

​Example Output

​Column Descriptions

​Configuration Details by Channel

​WhatsApp

​Telegram

​Discord

​Slack

​Feishu (Lark)

​DingTalk

​QQ

​Email

​Mochat

​Not Configured State

​channels login

​Usage

​Requirements

​First Run

​Scanning QR Code

​Subsequent Runs

​Bridge Directory

​Bridge Token

​Keep Bridge Running

​Configuration

​Troubleshooting

​npm Not Found

​Bridge Build Failed

​QR Code Not Showing

​WhatsApp Session Expired

​Bridge Connection Lost

​Gateway Not Routing Messages

​Running Multiple Channels

​Security

​Access Control

​Bridge Token

​Credentials

​Exit Codes

​Related Commands

​See Also

Build docs developers (and LLMs) love

Usage

Description

Subcommands

status

login

channels status

Usage

Example Output

Column Descriptions

Configuration Details by Channel

WhatsApp

Telegram

Discord

Slack

Feishu (Lark)

DingTalk

QQ

Email

Mochat

Not Configured State

channels login

Usage

Requirements

First Run

Scanning QR Code

Subsequent Runs

Bridge Directory

Bridge Token

Keep Bridge Running

Configuration

Troubleshooting

npm Not Found

Bridge Build Failed

QR Code Not Showing

WhatsApp Session Expired

Bridge Connection Lost

Gateway Not Routing Messages

Running Multiple Channels

Security

Access Control

Bridge Token

Credentials

Exit Codes

Related Commands

See Also