Adding Channels

Connect SimpleClaw to messaging platforms like WhatsApp, Telegram, Discord, and Slack

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:

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

Manual Channel Setup

WhatsApp

1. Enable WhatsApp Channel

   simpleclaw config set channels.whatsapp.enabled true --json
   
2. Link Your Device

   simpleclaw channels login --channel whatsapp
   

   A QR code will appear. Scan it with WhatsApp:

   1. Open WhatsApp on your phone
   2. Tap Menu or Settings → Linked Devices
   3. Tap Link a Device
   4. Scan the QR code
3. 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 '["[phone]"]' --json
   
4. Test Connection

   simpleclaw channels status --probe
   

   Send yourself a message on WhatsApp:

   Hello SimpleClaw!
   

Telegram

1. Create a Bot

   1. Open Telegram and message @BotFather
   2. Send /newbot
   3. Follow the prompts to choose a name and username
   4. Copy the bot token (looks like 123456:ABC-DEF1234)
2. 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"
   
3. Configure Allowlist (Optional)

   Restrict who can message your bot:

   simpleclaw config set channels.telegram.allowFrom '["@username"]' --json
   
4. Test Your Bot

   1. Find your bot in Telegram
   2. Send /start
   3. Send a message: “Hello!”

Discord

1. Create Discord Application

   1. Go to Discord Developer Portal
   2. Click New Application
   3. Name it (e.g., “SimpleClaw”)
   4. Go to Bot tab
   5. Click Add Bot
2. Enable Privileged Intents

   On the Bot page, enable:

   • Message Content Intent (required)
   • Server Members Intent (recommended)
3. 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
   
4. Add Bot to Server

   1. Go to OAuth2 → URL Generator
   2. Select scopes: bot, applications.commands
   3. Select bot permissions:
      • View Channels
      • Send Messages
      • Read Message History
      • Embed Links
      • Attach Files
   4. Copy the generated URL and open it in your browser
   5. Select your server and authorize
5. 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

1. Create Slack App

   1. Go to Slack API Apps
   2. Click Create New App → From scratch
   3. Name your app and select your workspace
2. Add Bot Scopes

   Go to OAuth & Permissions and add these scopes:

   • app_mentions:read
   • chat:write
   • channels:history
   • groups:history
   • im:history
   • files:write
3. Enable Socket Mode

   1. Go to Socket Mode and enable it
   2. Generate an app-level token with connections:write scope
   3. Copy the token (starts with xapp-)
4. Install to Workspace

   1. Go to Install App
   2. Click Install to Workspace
   3. Authorize the app
   4. Copy the Bot User OAuth Token (starts with xoxb-)
5. 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:

1. User Sends First Message

   Unknown user sends a DM:

   Hello!
   
2. Bot Responds with Pairing Code

   Your pairing code: ABC-123
   
   To approve: simpleclaw pairing approve <channel> ABC-123
   
3. Admin Approves Pairing

   On the machine running SimpleClaw:

   simpleclaw pairing approve telegram ABC-123
   
4. 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

1. Verify credentials are correct:

   simpleclaw config get channels.<channel-id>
   

2. Check Gateway logs:

   simpleclaw gateway logs --tail 50
   

3. Restart the Gateway:

   simpleclaw gateway restart
   

Messages not being received

1. Check allowlist configuration:

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

2. Verify DM policy:

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

3. Check channel status:

   simpleclaw channels status --probe
   

Bot not responding in groups

1. Verify group is in allowlist:

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

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