Messaging Channels: Complete Setup

#How Messaging Channels Work

Messaging channels are the primary way you interact with your OpenClaw agent. Instead of opening a terminal or dashboard, you simply send a message through your preferred platform — just like texting a friend. The agent receives your message, processes it through the LLM, and responds in the same channel.

OpenClaw supports multiple messaging platforms simultaneously. You can message your agent from Telegram on your phone, Discord on your desktop, and iMessage on your Mac — all conversations go to the same agent.

#Supported Platforms

#Telegram Setup

Telegram is the recommended first channel due to its simple bot API, rich features, and reliable delivery.

#Create a Telegram Bot

1. 1
   Open BotFather

   In Telegram, search for @BotFather and start a conversation. BotFather is Telegram's official tool for creating and managing bots.

2. 2
   Create a new bot

   Send /newbot to BotFather. It will ask for a display name (e.g., 'My OpenClaw Agent') and a username (must end in 'bot', e.g., 'my_openclaw_bot').

3. 3
   Copy the API token

   BotFather responds with an API token that looks like 7123456789:AAHfK3u2bIjKLM7nOpQrStUvWxYz. Copy this token — you will need it for OpenClaw configuration.

4. 4
   Configure bot settings (optional)

   Send /mybots to BotFather, select your bot, then 'Bot Settings'. Enable 'Inline Mode' if you want to use inline queries, and set 'Group Privacy' to disabled if you want the bot to see all messages in group chats.

#Configure OpenClaw

Add the Telegram token to your configuration. There is no openclaw config edit: either let the channels CLI write the token for you, or run openclaw config file, which "Prints the active config file path", and edit that file.

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "7123456789:AAHfK3u2bIjKLM7nOpQrStUvWxYz",
      "allowed_users": [123456789],
      "allow_groups": false,
      "polling_interval": 1000
    }
  }
}

#Find Your Telegram User ID

The allowed_users field restricts who can message your bot. To find your Telegram user ID:

1. Message @userinfobot on Telegram
2. It responds with your user ID (a number like 123456789)
3. Add this number to the allowed_users array

#Test the Connection

Restart the gateway and send a message:

Open Telegram, find your bot, and send "Hello". You should receive a response within a few seconds.

#WhatsApp Setup

WhatsApp integration uses the Meta Business API (formerly WhatsApp Business API). This requires more setup than Telegram but reaches the world's most popular messaging platform.

#Prerequisites

• A Meta Business account (business.facebook.com)
• A phone number dedicated to the WhatsApp bot (cannot be your personal number)
• A Meta App with WhatsApp product enabled

#Setup Steps

1. 1
   Create a Meta Business App

   Go to developers.facebook.com, create a new app of type 'Business', and add the 'WhatsApp' product to it.

2. 2
   Configure WhatsApp API

   In the WhatsApp product settings, add a phone number and verify it. Meta provides a test number for development.

3. 3
   Generate a permanent access token

   Under WhatsApp > Configuration, generate a permanent access token. The temporary tokens expire after 24 hours.

4. 4
   Set up the webhook

   Configure a webhook URL that points to your OpenClaw Gateway. The URL format is: https://your-domain/webhook/whatsapp. You will need a public URL (use Cloudflare Tunnel or ngrok for local installations).

5. 5
   Configure OpenClaw

   Add the WhatsApp credentials to openclaw.json.

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "phone_number_id": "1234567890",
      "access_token": "EAAxxxxxxx...",
      "verify_token": "your-custom-verify-token",
      "webhook_path": "/webhook/whatsapp",
      "allowed_numbers": ["+1234567890"]
    }
  }
}

#Discord Setup

Discord integration lets your agent respond in DMs or specific channels within a Discord server.

#Create a Discord Bot

1. 1
   Create a Discord Application

   Go to discord.com/developers/applications and click 'New Application'. Give it a name like 'OpenClaw Agent'.

2. 2
   Create a Bot user

   In the application settings, go to the 'Bot' section and click 'Add Bot'. Copy the bot token.

3. 3
   Configure intents

   Under 'Privileged Gateway Intents', enable 'Message Content Intent'. This allows the bot to read message content.

4. 4
   Generate an invite link

   Go to 'OAuth2 > URL Generator'. Select 'bot' scope and 'Send Messages', 'Read Messages/View Channels', and 'Read Message History' permissions. Copy the generated URL.

5. 5
   Invite the bot to your server

   Open the generated URL in your browser and select the server to add the bot to.

#Configure OpenClaw

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "MTIxxxxxxx.xxxxxxx.xxxxxxx",
      "allowed_users": ["your-discord-user-id"],
      "allowed_channels": ["channel-id-1", "channel-id-2"],
      "respond_to_mentions": true,
      "respond_to_dms": true
    }
  }
}

#Find Your Discord User ID

1. Open Discord Settings > Advanced > Enable Developer Mode
2. Right-click your username and select "Copy User ID"

#Find a Channel ID

With Developer Mode enabled, right-click any channel and select "Copy Channel ID".

#Slack Setup

Slack integration uses the Slack Bolt framework to connect your agent to a Slack workspace.

#Create a Slack App

1. 1
   Create the app

   Go to api.slack.com/apps and click 'Create New App'. Choose 'From scratch' and select your workspace.

2. 2
   Configure OAuth scopes

   Under 'OAuth & Permissions', add these Bot Token Scopes: chat:write, im:history, im:read, im:write, app_mentions:read, users:read.

3. 3
   Enable events

   Under 'Event Subscriptions', enable events and set the Request URL to your OpenClaw webhook endpoint: https://your-domain/webhook/slack. Subscribe to bot events: message.im, app_mention.

4. 4
   Install to workspace

   Under 'Install App', click 'Install to Workspace' and authorize. Copy the Bot User OAuth Token.

5. 5
   Get the signing secret

   Under 'Basic Information', copy the Signing Secret. This is used to verify requests from Slack.

#Configure OpenClaw

{
  "channels": {
    "slack": {
      "enabled": true,
      "bot_token": "xoxb-your-bot-token",
      "signing_secret": "your-signing-secret",
      "app_token": "xapp-your-app-token",
      "allowed_users": ["U1234567890"],
      "webhook_path": "/webhook/slack"
    }
  }
}

#iMessage Setup (macOS Only)

iMessage integration is the most native experience on Apple devices but requires macOS and some additional setup. It works by reading and sending iMessages through the macOS Messages framework.

#Prerequisites

• macOS with iMessage configured and signed in
• Full Disk Access permission granted to OpenClaw
• Accessibility permission granted to OpenClaw

#Configure OpenClaw

{
  "channels": {
    "imessage": {
      "enabled": true,
      "allowed_contacts": ["+1234567890", "user@icloud.com"],
      "read_receipts": true,
      "typing_indicators": true
    }
  }
}

#How It Works

OpenClaw monitors the iMessage database (~/Library/Messages/chat.db) for new messages from allowed contacts. When a message arrives, it processes it and sends a reply through the Messages app using AppleScript automation.

#Limitations

• Only works on macOS (not available on Linux or WSL2)
• Requires the macOS user to be logged in (with automatic login)
• Can be affected by macOS updates that change the Messages database schema
• Does not support group chats (DMs only)
• Sending images or files through iMessage requires additional configuration

#Multi-Channel Configuration

You can enable multiple channels simultaneously. Your agent maintains conversation context across channels — a conversation started on Telegram can be continued on Discord.

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "...",
      "allowed_users": [123456789]
    },
    "discord": {
      "enabled": true,
      "token": "...",
      "allowed_users": ["987654321"]
    },
    "imessage": {
      "enabled": true,
      "allowed_contacts": ["+1234567890"]
    }
  },
  "multi_channel": {
    "shared_context": true,
    "primary_channel": "telegram",
    "notification_channel": "telegram"
  }
}

#Multi-Channel Settings

• shared_context: When true, the agent remembers conversations across channels. A task started on Telegram can be followed up on Discord.
• primary_channel: The channel used for proactive messages (reminders, cron job results, alerts).
• notification_channel: Where the agent sends system notifications (health alerts, skill updates).

#DM Policy and Access Control

Controlling who can message your agent is critical for security and cost management. Every message costs API tokens, and unauthorized users could abuse your agent.

#Global DM Policy

{
  "security": {
    "dm_policy": {
      "default_action": "deny",
      "allow_unknown_users": false,
      "rate_limit": {
        "messages_per_minute": 10,
        "messages_per_hour": 100
      },
      "blocked_users": [],
      "admin_users": {
        "telegram": [123456789],
        "discord": ["987654321"]
      }
    }
  }
}

#Admin vs Regular Users

• Admin users can install skills, modify configuration, and access system commands through chat
• Regular users (in allowed_users but not admin_users) can chat with the agent but cannot perform administrative actions
• Unknown users are blocked by default when allow_unknown_users is false

#Testing Your Channels

After configuring one or more channels, restart the gateway and verify:

The health output shows connected channels:

Channels:  telegram (connected), discord (connected), imessage (connected)

If a channel shows disconnected or error, check:

1. The API token/credentials are correct
2. The bot has the required permissions on the platform
3. Network connectivity to the platform's API servers
4. Firewall rules allow outbound HTTPS traffic

Run diagnostics for a specific channel:

#Troubleshooting Channel Issues

#Telegram: Bot not responding

• Verify the token with BotFather (/mybots > your bot > API Token)
• Check that your user ID is in allowed_users
• Ensure the bot is not being used by another service (only one process can poll a Telegram bot)

#Discord: Bot is offline

• Verify the bot token in the Discord Developer Portal
• Check that Message Content Intent is enabled
• Ensure the bot has been invited to the server and has channel permissions

#WhatsApp: Webhook not receiving messages

• Verify the webhook URL is publicly accessible
• Check that the verify token matches between Meta and openclaw.json
• Ensure the webhook subscription is active in the Meta Developer Console

#iMessage: Messages not detected

• Verify Full Disk Access is granted to OpenClaw
• Check that you are logged into iMessage on the Mac
• Restart the Messages app and the OpenClaw Gateway

#Next Steps

• Security Hardening — Secure your messaging channels
• API Key Setup — Configure the LLM providers behind your channels
• SOUL.md Mastery — Customize how your agent responds
• Heartbeat & Cron — Set up proactive messages