Adding Channels

Connect SimpleClaw to your favorite messaging platforms to interact with your agent from anywhere.

Supported Channels

SimpleClaw supports these messaging platforms:

WhatsApp (via Baileys)
Telegram (via grammY)
Discord (via discord.js)
Slack (via Bolt)
Google Chat (Chat API)
Signal (signal-cli)
BlueBubbles (iMessage, recommended)
iMessage (legacy macOS)
Microsoft Teams (extension)
Matrix (extension)
WebChat (built-in web UI)

Quick Setup Wizard

The easiest way to add channels is using the onboarding wizard:

simpleclaw onboard --channels

The wizard will guide you through:

Selecting channels to enable
Providing credentials (API keys, bot tokens)
Configuring access control (allowlists, DM policies)
Testing channel connections

Manual Channel Setup

Enable WhatsApp Channel

simpleclaw config set channels.whatsapp.enabled true --json

Link Your Device

simpleclaw channels login --channel whatsapp

A QR code will appear. Scan it with WhatsApp:

Open WhatsApp on your phone
Tap Menu or Settings → Linked Devices
Tap Link a Device
Scan the QR code

Configure Allowlist

Only allow specific contacts to message the agent:

simpleclaw config set channels.whatsapp.allowFrom '["<phone-number>"]' --json

Example:

simpleclaw config set channels.whatsapp.allowFrom '["+15551234567"]' --json

Test Connection

simpleclaw channels status --probe

Send yourself a message on WhatsApp:

Hello SimpleClaw!

Create a Bot

Open Telegram and message @BotFather
Send /newbot
Follow the prompts to choose a name and username
Copy the bot token (looks like 123456:ABC-DEF1234)

Configure Bot Token

Set the token in your config:

simpleclaw config set channels.telegram.botToken '"YOUR_BOT_TOKEN"' --json
simpleclaw config set channels.telegram.enabled true --json

Or use environment variable:

export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234"

Configure Allowlist (Optional)

Restrict who can message your bot:

simpleclaw config set channels.telegram.allowFrom '["@username"]' --json

Test Your Bot

Find your bot in Telegram
Send /start
Send a message: “Hello!”

Discord

Create Discord Application

Go to Discord Developer Portal
Click New Application
Name it (e.g., “SimpleClaw”)
Go to Bot tab
Click Add Bot

Enable Privileged Intents

On the Bot page, enable:

Message Content Intent (required)
Server Members Intent (recommended)

Get Bot Token

Click Reset Token and copy the token.Set it in config:

simpleclaw config set channels.discord.token '"YOUR_BOT_TOKEN"' --json
simpleclaw config set channels.discord.enabled true --json

Add Bot to Server

Go to OAuth2 → URL Generator
Select scopes: bot, applications.commands
Select bot permissions:
- View Channels
- Send Messages
- Read Message History
- Embed Links
- Attach Files
Copy the generated URL and open it in your browser
Select your server and authorize

Configure DM Policy

Discord DMs default to pairing mode. To allow open DMs:

simpleclaw config set channels.discord.dmPolicy '"open"' --json
simpleclaw config set channels.discord.allowFrom '["*"]' --json

Or keep pairing mode (recommended):

simpleclaw config set channels.discord.dmPolicy '"pairing"' --json

Slack

Create Slack App

Go to Slack API Apps
Click Create New App → From scratch
Name your app and select your workspace

Add Bot Scopes

Go to OAuth & Permissions and add these scopes:

app_mentions:read
chat:write
channels:history
groups:history
im:history
files:write

Enable Socket Mode

Go to Socket Mode and enable it
Generate an app-level token with connections:write scope
Copy the token (starts with xapp-)

Install to Workspace

Go to Install App
Click Install to Workspace
Authorize the app
Copy the Bot User OAuth Token (starts with xoxb-)

Configure Tokens

export SLACK_BOT_TOKEN="xoxb-your-bot-token"
export SLACK_APP_TOKEN="xapp-your-app-token"

Or in config:

simpleclaw config set channels.slack.botToken '"xoxb-..."' --json
simpleclaw config set channels.slack.appToken '"xapp-..."' --json
simpleclaw config set channels.slack.enabled true --json

Channel Configuration Reference

Common Options

All channels support these config options:

{
  "channels": {
    "<channel-id>": {
      "enabled": true,
      "allowFrom": ["user-id-1", "user-id-2"],
      "dmPolicy": "pairing",  // or "open", "blocked"
      "groups": {
        "group-id-1": {
          "requireMention": true
        },
        "*": {
          "requireMention": false
        }
      }
    }
  }
}

DM Policies

dmPolicy

string

default:"pairing"

How to handle direct messages from unknown senders:

pairing - Require pairing code approval (recommended)
open - Allow anyone to message (requires "*" in allowFrom)
blocked - Reject all DMs from non-allowlisted senders

Group Configuration

groups

object

Configure group chat behavior:

{
  "groups": {
    "specific-group-id": {
      "requireMention": true,
      "allowUnmentionedTools": false
    },
    "*": {
      "requireMention": false
    }
  }
}

Use "*" as a wildcard to allow all groups.

Channel Status

Check the health of all channels:

simpleclaw channels status

With active probing:

simpleclaw channels status --probe

Example output:

┌─ Channels Status ────────────────────────────────────┐
│ WhatsApp     ✓ Connected                              │
│ Telegram     ✓ Connected (@your_bot)                  │
│ Discord      ✓ Connected (2 servers)                 │
│ Slack        ✗ Not configured                         │
└──────────────────────────────────────────────────┘

Pairing Flow (DM Access)

When using dmPolicy: "pairing", unknown senders receive a pairing code:

User Sends First Message

Unknown user sends a DM:

Hello!

Bot Responds with Pairing Code

Your pairing code: ABC-123

To approve: simpleclaw pairing approve <channel> ABC-123

Admin Approves Pairing

On the machine running SimpleClaw:

simpleclaw pairing approve telegram ABC-123

User Can Now Chat

The user is added to the allowlist and can now message the agent.

Multi-Account Setup

Some channels support multiple accounts:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "work": {
          "botToken": "123456:WORK_TOKEN",
          "allowFrom": ["@work_team"]
        },
        "personal": {
          "botToken": "789012:PERSONAL_TOKEN",
          "allowFrom": ["@family"]
        }
      }
    }
  }
}

Troubleshooting

Channel not connecting

Verify credentials are correct:

simpleclaw config get channels.<channel-id>

Check Gateway logs:
```
simpleclaw gateway logs --tail 50
```
Restart the Gateway:
```
simpleclaw gateway restart
```

Messages not being received

Check allowlist configuration:

simpleclaw config get channels.<channel-id>.allowFrom

Verify DM policy:

simpleclaw config get channels.<channel-id>.dmPolicy

Check channel status:
```
simpleclaw channels status --probe
```

Bot not responding in groups

Verify group is in allowlist:

{
  "groups": {
    "group-id": { "requireMention": true },
    "*": { "requireMention": false }
  }
}

Check if mention is required:
- Discord: @BotName message
- Telegram: @bot_username message
- Slack: @BotName message

Next Steps

Multi-Agent Setup

Route different channels to specialized agents

Custom Skills

Add custom tools and capabilities

Webhooks

Trigger agent runs from external events

Troubleshooting

Common issues and solutions

Setup Guides

Advanced

Adding Channels

Adding Channels

Supported Channels

Quick Setup Wizard

Manual Channel Setup

WhatsApp

Telegram

Discord

Slack

Channel Configuration Reference

Common Options

DM Policies

Group Configuration

Channel Status

Pairing Flow (DM Access)

Multi-Account Setup

Troubleshooting

Next Steps

Multi-Agent Setup

Custom Skills

Webhooks

Troubleshooting

Build docs developers (and LLMs) love

Setup Guides

Advanced

​Adding Channels

​Supported Channels

​Quick Setup Wizard

​Manual Channel Setup

​WhatsApp

​Telegram

​Discord

​Slack

​Channel Configuration Reference

​Common Options

​DM Policies

​Group Configuration

​Channel Status

​Pairing Flow (DM Access)

​Multi-Account Setup

​Troubleshooting

​Next Steps

Multi-Agent Setup

Custom Skills

Webhooks

Troubleshooting

Build docs developers (and LLMs) love

Adding Channels

Supported Channels

Quick Setup Wizard

Manual Channel Setup

WhatsApp

Telegram

Discord

Slack

Channel Configuration Reference

Common Options

DM Policies

Group Configuration

Channel Status

Pairing Flow (DM Access)

Multi-Account Setup

Troubleshooting

Next Steps