WhatsApp & Telegram Setup

+15 Mana ✨
OpenClaw WhatsApp Channel(DOCUMENTATION)OpenClaw Telegram Channel(DOCUMENTATION)

Introduction

WhatsApp and Telegram are two of the most popular messaging platforms worldwide, making them prime targets for deploying your OpenClaw assistant. WhatsApp uses the Baileys library with QR code authentication, while Telegram relies on the grammY framework with a BotFather-issued token. This lesson walks you through configuring both channels from scratch.

Key Concepts

  • Baileys: An unofficial WhatsApp Web API library that OpenClaw uses to connect to WhatsApp without requiring the official Business API.
  • QR Code Authentication: The process of scanning a QR code from your WhatsApp mobile app to link OpenClaw as a WhatsApp Web client.
  • E.164 Format: The international phone number standard (e.g., +14155551234) used in WhatsApp's allowFrom configuration to specify which numbers can interact with your assistant.
  • BotFather: Telegram's official bot for creating and managing bot accounts. You interact with @BotFather on Telegram to obtain your bot's API token.
  • Long Polling vs Webhook: Two methods for receiving Telegram updates. Long polling (the default) continuously asks Telegram for new messages, while webhooks have Telegram push messages to a URL you specify.
  • Text Chunking: WhatsApp automatically splits messages longer than 4000 characters into multiple parts.
  • ackReaction: An emoji reaction OpenClaw sends on WhatsApp to acknowledge it received a message before processing.

Real World Context

Consider a small business that uses WhatsApp for customer support and Telegram for their developer community. The support team wants an AI assistant that answers common product questions on WhatsApp, while the developer community wants the same assistant available in their Telegram group for technical queries. With OpenClaw, you configure both channels in a single instance. The WhatsApp channel handles customer conversations with phone number allowlists, while the Telegram channel serves the group with privacy mode disabled so the bot can read all messages.

Deep Dive

WhatsApp Setup

WhatsApp integration uses the Baileys library, which emulates a WhatsApp Web client. Authentication happens via QR code, just like linking WhatsApp Web on a computer.

First, initiate the login process:

bash
openclaw channels login --channel whatsapp

This command generates a QR code in your terminal. You then open WhatsApp on your phone, go to Linked Devices, and scan the QR code. Once scanned, OpenClaw establishes a persistent session with WhatsApp.

After authentication, configure your WhatsApp channel settings:

json
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": [
        "+14155551234",
        "+442071234567"
      ],
      "ackReaction": "👀",
      "textChunkSize": 4000
    }
  }
}

The allowFrom field accepts an array of phone numbers in E.164 format. Only messages from these numbers will be processed. The ackReaction field sets the emoji that OpenClaw reacts with when it receives a message, giving the user immediate visual feedback. The textChunkSize field controls where long responses get split; WhatsApp's limit is 4000 characters per message.

WhatsApp also supports media. Your assistant can receive and send images, documents, audio, and video. The Baileys connector handles media upload and download automatically.

Telegram Setup

Telegram uses a more traditional bot API approach. Start by creating your bot through BotFather:

  1. Open Telegram and search for @BotFather
  2. Send the /newbot command
  3. Follow the prompts to name your bot and choose a username
  4. BotFather returns an API token

Configure the token in your OpenClaw settings:

json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp"
    }
  }
}

The token field holds the API token from BotFather. Alternatively, you can set the TELEGRAM_BOT_TOKEN environment variable instead of putting the token in your config file, which is more secure for production deployments.

By default, Telegram uses long polling to receive updates. This works well for most deployments without requiring a public URL. If you prefer webhooks for lower latency, you can configure a webhook URL in the Telegram channel settings.

For group chats, you must disable Telegram's privacy mode. By default, bots in Telegram groups only receive messages that mention them directly or are replies to their messages. To let your assistant see all group messages, go to @BotFather, select your bot, choose Bot Settings, then Group Privacy, and set it to Disabled.

Telegram also supports streaming responses. You can configure this as partial streaming (sending incremental updates to a single message) or block streaming (sending complete chunks as separate messages):

json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "streaming": "partial"
    }
  }
}

The streaming field accepts "partial" to edit a single message as the response generates, or "block" to send complete paragraphs as separate messages. This gives users real-time feedback while the assistant is thinking.

Common Pitfalls

  • WhatsApp session expiration: The QR code session can expire if your phone loses internet connectivity for an extended period. You will need to re-run openclaw channels login --channel whatsapp and scan a new QR code.
  • Telegram privacy mode blocking group messages: If your bot is not responding in groups, the most common cause is that privacy mode is still enabled. Always disable it via @BotFather when you want the bot to participate in group conversations.
  • Hardcoding tokens in config files: Putting your Telegram token directly in the config file is convenient for development but risky for production. Use the TELEGRAM_BOT_TOKEN environment variable to keep secrets out of version control.

Best Practices

  • Use allowFrom on WhatsApp: Always restrict which phone numbers can interact with your assistant in production. An open WhatsApp channel can quickly exhaust your compute and API resources.
  • Set an ackReaction on WhatsApp: The acknowledgment emoji gives users immediate feedback that their message was received, which improves perceived responsiveness even before the assistant generates a reply.
  • Prefer long polling for Telegram in development: Webhooks require a publicly accessible HTTPS URL. During development, long polling works without any networking setup.

Summary

  • WhatsApp connects via the Baileys library using QR code authentication initiated by openclaw channels login --channel whatsapp.
  • WhatsApp uses E.164 phone numbers in allowFrom, supports media, and chunks text at 4000 characters.
  • Telegram bots are created through @BotFather's /newbot command, which provides an API token.
  • Telegram defaults to long polling and supports streaming responses in partial or block mode.
  • Privacy mode must be disabled on Telegram bots for them to read all group messages.
✓ Completed