Lesson 5. Connecting a Messenger#

Why this lesson?#

So far, we’ve been chatting with AI through the web interface or terminal. But the real magic of OpenClaw is the ability to message the assistant directly in Telegram or WhatsApp, like a regular contact. In this lesson, we’ll set that up.

Option A: Connecting Telegram#

Telegram is the easiest way to connect a messenger to OpenClaw. You’ll create a bot in Telegram and communicate with AI through it.

A Telegram bot is a special account controlled by a program, not a person. You message the bot — OpenClaw receives the message, sends it to AI, and sends the response back.

Step 1. Create a bot in Telegram#

1. Open Telegram on your phone or computer
2. Search for @BotFather (this is Telegram’s official bot for creating other bots)
3. Make sure it’s exactly @BotFather with the blue checkmark
4. Send it: /newbot
5. BotFather will ask for the bot name — enter anything (for example, “My AI Assistant”)
6. Then it will ask for a username — this is a unique name that must end with bot (for example, my_ai_helper_bot)
7. BotFather will send you a token — a long string like 123456789:ABCDefGhIJKlMNoPQRstuVWxyz

⚠️ The token is like a password for your bot. Don’t share it with anyone!

Step 2. Add the token to OpenClaw settings#

If you used the setup wizard (openclaw onboard), it may have asked about Telegram. If not — we’ll add it manually.

Open the OpenClaw configuration file. It’s usually located at:

~/.openclaw/openclaw.json

The ~ symbol means your home folder. On macOS it’s /Users/your_name/, on Linux — /home/your_name/.

Find or add the channels section:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TOKEN_FROM_BOTFATHER",
      "dmPolicy": "pairing"
    }
  }
}

dmPolicy: "pairing" is a security policy. It means the bot won’t respond to just anyone: each new user must be approved by you.

Step 3. Restart Gateway#

openclaw gateway restart

Step 4. Message the bot and approve yourself#

1. Open Telegram and find your bot by username (for example, @my_ai_helper_bot)
2. Send it “Hello”
3. The bot won’t respond yet — first you need to approve your account

In the terminal, run:

openclaw pairing list telegram

You’ll see a request code. Approve it:

openclaw pairing approve telegram CODE

Now message the bot again — it will respond! 🎉

Option B: Connecting WhatsApp#

WhatsApp is connected differently: OpenClaw uses WhatsApp Web (as if you opened WhatsApp on your computer).

Step 1. Configure settings#

In the file ~/.openclaw/openclaw.json, add:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": ["+15555550123"]
    }
  }
}

In allowFrom, specify your phone number in international format.

Step 2. Link WhatsApp#

openclaw channels login --channel whatsapp

A QR code will appear on screen. Scan it in WhatsApp:

1. Open WhatsApp on your phone
2. Go to Settings → Linked Devices → Link a Device
3. Point your camera at the QR code in the terminal

Step 3. Start and verify#

openclaw gateway restart

Now send a message to your WhatsApp number (from another number or through a contact) — and AI will respond!

What other messengers are supported?#

OpenClaw supports many channels:

Lesson summary#

• You can chat with AI through Telegram or WhatsApp — like with a regular contact
• For Telegram, you need to create a bot through @BotFather and add the token to settings
• For WhatsApp, you need to scan a QR code, just like linking a device
• The pairing system protects the bot: it only responds to approved users
• OpenClaw supports more than 10 messengers

In the next lesson, we’ll set up the assistant’s personality — give it a name, character, and behavior rules!