picoclaw/docs/chat-apps.md

💬 Chat Apps Configuration

Back to README

💬 Chat Apps

Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, WeCom, Feishu, Slack, IRC, OneBot, MaixCam, or Pico (native protocol)

Note

: All webhook-based channels (LINE, WeCom, etc.) are served on a single shared Gateway HTTP server (gateway.host:gateway.port, default 127.0.0.1:18790). There are no per-channel ports to configure. Note: Feishu uses WebSocket/SDK mode and does not use the shared HTTP webhook server.

Channel	Setup
Telegram	Easy (just a token)
Discord	Easy (bot token + intents)
WhatsApp	Easy (native: QR scan; or bridge URL)
Matrix	Medium (homeserver + bot access token)
QQ	Easy (AppID + AppSecret)
DingTalk	Medium (app credentials)
LINE	Medium (credentials + webhook URL)
WeCom AI Bot	Medium (Token + AES key)
Feishu	Medium (App ID + Secret, WebSocket mode)
Slack	Medium (Bot token + App token)
IRC	Medium (server + TLS config)
OneBot	Medium (QQ via OneBot protocol)
MaixCam	Easy (Sipeed hardware integration)
Pico	Native PicoClaw protocol

Telegram (Recommended)

1. Create a bot

• Open Telegram, search @BotFather
• Send /newbot, follow prompts
• Copy the token

2. Configure

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"],
      "use_markdown_v2": false,
    }
  }
}

Get your user ID from @userinfobot on Telegram.

3. Run

picoclaw gateway

4. Telegram command menu (auto-registered at startup)

PicoClaw now keeps command definitions in one shared registry. On startup, Telegram will automatically register supported bot commands (for example /start, /help, /show, /list) so command menu and runtime behavior stay in sync. Telegram command menu registration remains channel-local discovery UX; generic command execution is handled centrally in the agent loop via the commands executor.

If command registration fails (network/API transient errors), the channel still starts and PicoClaw retries registration in the background.

4. Advanced Formatting You can set use_markdown_v2: true to enable enhanced formatting options. This allows the bot to utilize the full range of Telegram MarkdownV2 features, including nested styles, spoilers, and custom fixed-width blocks.

Discord

1. Create a bot

• Go to https://discord.com/developers/applications
• Create an application → Bot → Add Bot
• Copy the bot token

2. Enable intents

• In the Bot settings, enable MESSAGE CONTENT INTENT
• (Optional) Enable SERVER MEMBERS INTENT if you plan to use allow lists based on member data

3. Get your User ID

• Discord Settings → Advanced → enable Developer Mode
• Right-click your avatar → Copy User ID

4. Configure

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}

5. Invite the bot

• OAuth2 → URL Generator
• Scopes: bot
• Bot Permissions: Send Messages, Read Message History
• Open the generated invite URL and add the bot to your server

Optional: Group trigger mode

By default the bot responds to all messages in a server channel. To restrict responses to @-mentions only, add:

{
  "channels": {
    "discord": {
      "group_trigger": { "mention_only": true }
    }
  }
}

You can also trigger by keyword prefixes (e.g. !bot):

{
  "channels": {
    "discord": {
      "group_trigger": { "prefixes": ["!bot"] }
    }
  }
}

6. Run

picoclaw gateway

WhatsApp (native via whatsmeow)

PicoClaw can connect to WhatsApp in two ways:

• Native (recommended): In-process using whatsmeow. No separate bridge. Set "use_native": true and leave bridge_url empty. On first run, scan the QR code with WhatsApp (Linked Devices). Session is stored under your workspace (e.g. workspace/whatsapp/). The native channel is optional to keep the default binary small; build with -tags whatsapp_native (e.g. make build-whatsapp-native or go build -tags whatsapp_native ./cmd/...).
• Bridge: Connect to an external WebSocket bridge. Set bridge_url (e.g. ws://localhost:3001) and keep use_native false.

Configure (native)

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "use_native": true,
      "session_store_path": "",
      "allow_from": []
    }
  }
}

If session_store_path is empty, the session is stored in <workspace>/whatsapp/. Run picoclaw gateway; on first run, scan the QR code printed in the terminal with WhatsApp → Linked Devices.

QQ

1. Create a bot

• Go to QQ Open Platform
• Create an application → Get AppID and AppSecret

2. Configure

{
  "channels": {
    "qq": {
      "enabled": true,
      "app_id": "YOUR_APP_ID",
      "app_secret": "YOUR_APP_SECRET",
      "allow_from": []
    }
  }
}

Set allow_from to empty to allow all users, or specify QQ numbers to restrict access.

3. Run

picoclaw gateway

DingTalk

1. Create a bot

• Go to Open Platform
• Create an internal app
• Copy Client ID and Client Secret

2. Configure

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "allow_from": []
    }
  }
}

Set allow_from to empty to allow all users, or specify DingTalk user IDs to restrict access.

3. Run

picoclaw gateway

Matrix

1. Prepare bot account

• Use your preferred homeserver (e.g. https://matrix.org or self-hosted)
• Create a bot user and obtain its access token

2. Configure

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "user_id": "@your-bot:matrix.org",
      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
      "allow_from": []
    }
  }
}

3. Run

picoclaw gateway

For full options (device_id, join_on_invite, group_trigger, placeholder, reasoning_channel_id), see Matrix Channel Configuration Guide.

LINE

1. Create a LINE Official Account

• Go to LINE Developers Console
• Create a provider → Create a Messaging API channel
• Copy Channel Secret and Channel Access Token

2. Configure

{
  "channels": {
    "line": {
      "enabled": true,
      "channel_secret": "YOUR_CHANNEL_SECRET",
      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
      "webhook_path": "/webhook/line",
      "allow_from": []
    }
  }
}

LINE webhook is served on the shared Gateway server (gateway.host:gateway.port, default 127.0.0.1:18790).

3. Set up Webhook URL

LINE requires HTTPS for webhooks. Use a reverse proxy or tunnel:

# Example with ngrok (gateway default port is 18790)
ngrok http 18790

Then set the Webhook URL in LINE Developers Console to https://your-domain/webhook/line and enable Use webhook.

4. Run

picoclaw gateway

In group chats, the bot responds only when @mentioned. Replies quote the original message.

WeCom (企业微信)

PicoClaw supports three types of WeCom integration:

Option 1: WeCom Bot (Bot) - Easier setup, supports group chats Option 2: WeCom App (Custom App) - More features, proactive messaging, private chat only Option 3: WeCom AI Bot (AI Bot) - Official AI Bot, streaming replies, supports group & private chat

See WeCom AI Bot Configuration Guide for detailed setup instructions.

Quick Setup - WeCom Bot:

1. Create a bot

• Go to WeCom Admin Console → Group Chat → Add Group Bot
• Copy the webhook URL (format: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx)

2. Configure

{
  "channels": {
    "wecom": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
      "webhook_path": "/webhook/wecom",
      "allow_from": []
    }
  }
}

WeCom webhook is served on the shared Gateway server (gateway.host:gateway.port, default 127.0.0.1:18790).

Quick Setup - WeCom App:

1. Create an app

• Go to WeCom Admin Console → App Management → Create App
• Copy AgentId and Secret
• Go to "My Company" page, copy CorpID

2. Configure receive message

• In App details, click "Receive Message" → "Set API"
• Set URL to http://your-server:18790/webhook/wecom-app
• Generate Token and EncodingAESKey

3. Configure

{
  "channels": {
    "wecom_app": {
      "enabled": true,
      "corp_id": "wwxxxxxxxxxxxxxxxx",
      "corp_secret": "YOUR_CORP_SECRET",
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-app",
      "allow_from": []
    }
  }
}

4. Run

picoclaw gateway

Note

: WeCom webhook callbacks are served on the Gateway port (default 18790). Use a reverse proxy for HTTPS.

Quick Setup - WeCom AI Bot:

1. Create an AI Bot

• Go to WeCom Admin Console → App Management → AI Bot
• In the AI Bot settings, configure callback URL: http://your-server:18791/webhook/wecom-aibot
• Copy Token and click "Random Generate" for EncodingAESKey

2. Configure

{
  "channels": {
    "wecom_aibot": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
      "welcome_message": "Hello! How can I help you?",
      "processing_message": "⏳ Processing, please wait. The results will be sent shortly."
    }
  }
}

3. Run

picoclaw gateway

Note

: WeCom AI Bot uses streaming pull protocol — no reply timeout concerns. Long tasks (>30 seconds) automatically switch to response_url push delivery.