Channel Adapters

Channel Adapters

Connect PocketPaw to Discord, Slack, WhatsApp, Telegram, and the web dashboard.

Overview

PocketPaw uses a message bus architecture where channel adapters translate between external platforms and the internal InboundMessage/OutboundMessage format. Multiple channels can run simultaneously.

Available Channels

Quick Start

Web Dashboard (Default)

No flags needed — the dashboard is the default mode:

uv run pocketpaw
# Dashboard at http://localhost:8888

All configured adapters auto-start on launch. Manage channels from the sidebar "Channels" button.

Headless Mode

Run specific channels without the dashboard:

# Single channel
uv run pocketpaw --discord
uv run pocketpaw --slack
uv run pocketpaw --whatsapp

# Multiple channels
uv run pocketpaw --discord --slack

# Legacy Telegram mode
uv run pocketpaw --telegram

Discord

Setup

1. Create a Discord bot at discord.com/developers
2. Enable Message Content Intent under Bot settings
3. Generate a bot token
4. Invite the bot to your server with appropriate permissions

Configuration

{
  "discord_bot_token": "your-bot-token",
  "discord_allowed_guild_ids": [123456789],
  "discord_allowed_user_ids": [987654321]
}

Or via environment variables:

export POCKETCLAW_DISCORD_BOT_TOKEN=your-bot-token
export POCKETCLAW_DISCORD_ALLOWED_GUILD_IDS='[123456789]'

Features

• Slash command: /paw <message> for agent interaction
• DM support: Send direct messages to the bot
• Mentions: @BotName <message> in any allowed channel
• Streaming: Responses are edited in-place as chunks arrive (1.5s rate limit)
• Access control: Restrict by guild ID and/or user ID

Auto-Install

If discord.py is not installed, PocketPaw will automatically install it when the adapter starts.

Slack

Setup

1. Create a Slack app at api.slack.com/apps
2. Enable Socket Mode (no public URL needed)
3. Add bot scopes: app_mentions:read, chat:write, im:history, im:read, im:write
4. Generate a Bot Token (xoxb-...) and App-Level Token (xapp-...)

Configuration

{
  "slack_bot_token": "xoxb-your-bot-token",
  "slack_app_token": "xapp-your-app-token",
  "slack_allowed_channel_ids": ["C01234567"]
}

Features

• Socket Mode: No public URL or webhooks needed
• App mentions: @PocketPaw <message> in channels
• DM support: Direct messages to the bot
• Thread support: Conversations maintain thread context via thread_ts
• Access control: Restrict by channel ID

Auto-Install

If slack-bolt is not installed, PocketPaw will automatically install it when the adapter starts.

WhatsApp

PocketPaw supports two WhatsApp modes:

Personal Mode (QR Scan)

Uses the neonize library (WhatsApp Web multi-device protocol). No Meta Developer account needed.

How it works:

1. Start PocketPaw with the web dashboard
2. Go to Channels > WhatsApp > select "Personal (QR Scan)"
3. Click "Start WhatsApp"
4. Scan the QR code with your phone's WhatsApp (Linked Devices)
5. You're connected — send messages from any WhatsApp chat

Configuration:

{
  "whatsapp_mode": "personal",
  "whatsapp_neonize_db": ""
}

The whatsapp_neonize_db field is optional — defaults to ~/.pocketclaw/neonize.sqlite3. This stores your WhatsApp session credentials.

Features:

• QR-code-scan pairing (just like WhatsApp Web)
• No Meta Developer account, webhooks, or tunnels required
• Credentials persist across restarts (re-scan not needed)
• Real-time QR display in dashboard (polls every 2s)
• Connected status indicator

Auto-Install: If neonize is not installed, PocketPaw will automatically install it when the adapter starts.

Business Mode (Cloud API)

Uses the WhatsApp Business Cloud API (Meta). Requires a Meta Developer account.

Configuration:

{
  "whatsapp_mode": "business",
  "whatsapp_access_token": "your-access-token",
  "whatsapp_phone_number_id": "your-phone-number-id",
  "whatsapp_verify_token": "your-verify-token",
  "whatsapp_allowed_phone_numbers": ["+1234567890"]
}

Requirements:

• Meta Developer account with WhatsApp Business API access
• Registered business phone number
• Public webhook URL (use PocketPaw's Cloudflare tunnel or your own)

Webhook routes:

• GET /webhook/whatsapp — Meta verification challenge
• POST /webhook/whatsapp — Incoming message delivery

Dashboard Channel Management

The web dashboard provides a GUI for managing all channels:

REST API

Channel Status Response

{
  "discord": {"configured": true, "running": true},
  "slack": {"configured": false, "running": false},
  "whatsapp": {"configured": true, "running": true, "mode": "personal"},
  "telegram": {"configured": true, "running": false}
}

Auto-Install System

Optional dependencies (discord.py, slack-bolt, neonize) are automatically installed when an adapter starts and the package is missing. The system:

1. Detects ImportError when the adapter tries to import its library
2. Runs uv pip install pocketpaw[extra] (falls back to pip install if uv is not available)
3. Verifies the import succeeds after installation
4. Raises RuntimeError with a clear message if installation fails

This means users don't need to manually install optional dependencies — just configure a channel and start it.

Implementation

Tests

• tests/test_discord_adapter.py — 11 tests
• tests/test_slack_adapter.py — 11 tests
• tests/test_whatsapp_adapter.py — 13 tests
• tests/test_neonize_adapter.py — 15 tests
• tests/test_bus.py — 9 tests (including cross-channel pub/sub)