Chapter 7: WhatsApp & iMessage Setup

WhatsApp and iMessage are the two most widely used personal messaging apps globally. Connecting them to OpenClaw gives your AI agents a mobile-first presence — accessible from any phone without installing a new app. This chapter covers the complete setup process for both channels.

---

Part 1: WhatsApp

OpenClaw supports two methods for WhatsApp integration:

Method	API Used	Best For
WhatsApp Business API	Official Meta API	Production, high-volume, business use
Baileys (unofficial)	Reverse-engineered	Personal use, development, testing

Method A: WhatsApp Business API (Production)

The official WhatsApp Business API is the recommended path for any team or client-facing deployment.

Prerequisites

• A Meta Business Account (business.facebook.com)
• A phone number dedicated to your WhatsApp bot (cannot be a number already registered on WhatsApp)
• A Permanent HTTPS URL for your webhook (your gateway must be publicly reachable)

Step 1: Create a Meta App

1. Go to developers.facebook.com
2. Click My Apps → Create App
3. Select Business type
4. Add WhatsApp product to the app

Step 2: Register Your Phone Number

1. In the WhatsApp product panel, go to Getting Started
2. Click Add phone number
3. Verify the number via SMS or phone call
4. Note the Phone Number ID and WhatsApp Business Account ID

Step 3: Generate a Permanent Token

1. Go to System Users in your Meta Business settings
2. Create a system user with Admin role
3. Assign the user to your WhatsApp app
4. Generate a never-expiring token (select whatsapp_business_messaging and whatsapp_business_management permissions)

Step 4: Configure the Webhook

1. In your WhatsApp app, go to Webhooks → Configure
2. Set the Callback URL to: https://your-domain.com/webhooks/whatsapp
3. Set the Verify Token to any random string you choose (you will put it in openclaw.json)
4. Subscribe to: messages, message_deliveries, message_reads

Step 5: Configure openclaw.json

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "method": "business-api",
      "phoneNumberId": "123456789012345",
      "wabaId": "987654321098765",
      "accessToken": "${WHATSAPP_ACCESS_TOKEN}",
      "verifyToken": "${WHATSAPP_VERIFY_TOKEN}",
      "webhookPath": "/webhooks/whatsapp"
    }
  }
}

Set your environment variables:

export WHATSAPP_ACCESS_TOKEN="EAAxxxxxx..."
export WHATSAPP_VERIFY_TOKEN="my-secret-verify-token-abc123"

Step 6: Start and Test

openclaw start

Send a message from any WhatsApp account to your registered business number. You should receive a response from your AI agent within seconds.

---

Method B: Baileys (Personal / Development)

Baileys is an open-source WhatsApp Web library that connects via QR code scanning — no business account needed.

Warning: This method uses the unofficial WhatsApp Web protocol. Meta does not support it. Use only for personal projects and development testing.

Step 1: Enable Baileys in openclaw.json

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "method": "baileys"
    }
  }
}

Step 2: Authenticate via QR Code

openclaw start

The gateway prints a QR code in the terminal:

Scan this QR code with WhatsApp to connect:
[QR CODE DISPLAYED HERE]

Open WhatsApp on your phone → Settings → Linked Devices → Link a Device → Scan the QR code.

Step 3: Verify Connection

openclaw channel status whatsapp

Output: whatsapp: connected (baileys) | linked to: +1234567890

Baileys stores the session in ~/.openclaw/sessions/whatsapp-baileys/ so you do not need to re-scan on restart.

---

WhatsApp Allowlist

Add users by their international phone number (with + prefix):

{
  "workspaces": [
    {
      "id": "clients",
      "channels": ["whatsapp"],
      "allowlist": ["+923001234567", "+14155552671"]
    }
  ]
}

To allow all WhatsApp users (open bot):

{
  "allowlist": ["*"]
}

---

Part 2: iMessage

iMessage integration requires a Mac running macOS as your gateway host. It uses the imessage-rest service to read and send iMessages programmatically.

Prerequisites

• Mac running macOS 13 (Ventura) or later
• Messages app signed in with an Apple ID
• Full Disk Access granted to Terminal / your shell
• OpenClaw gateway running on the same Mac

Step 1: Install imessage-rest

brew install python@3.11
pip3 install imessage-rest

Or with npm:

npm install -g imessage-rest

Step 2: Grant Permissions

iMessage requires Full Disk Access to read the chat.db SQLite file:

1. Open System Settings → Privacy & Security → Full Disk Access
2. Click + and add your terminal app (Terminal, iTerm2, Warp, etc.)
3. Restart your terminal

Step 3: Start imessage-rest

imessage-rest start --port 8000

Keep this running. It exposes a local REST API that OpenClaw uses to read and send iMessages.

Step 4: Configure openclaw.json

{
  "channels": {
    "imessage": {
      "enabled": true,
      "imessageRestUrl": "http://localhost:8000",
      "pollInterval": 2000
    }
  }
}

pollInterval is in milliseconds. The gateway checks for new iMessages every 2 seconds.

Step 5: iMessage Allowlist

Add users by their Apple ID email or phone number:

{
  "workspaces": [
    {
      "id": "personal",
      "channels": ["imessage"],
      "allowlist": ["user@icloud.com", "+14155552671"]
    }
  ]
}

Step 6: Test the Connection

openclaw start
openclaw channel status imessage

Send an iMessage to your gateway Mac's Apple ID from another device. The response should arrive within 2–4 seconds.

---

Troubleshooting

WhatsApp Business API

Problem	Solution
Webhook verification fails	Check verify token matches in Meta dashboard and openclaw.json
Messages not received	Confirm webhook subscriptions include messages
Token expired	Generate a new system user token; use permanent (never-expiring) tokens
Phone number already registered	Use a fresh number not previously used with WhatsApp

WhatsApp Baileys

Problem	Solution
QR code expired	Run openclaw channel restart whatsapp to generate a new QR
Frequent disconnections	This is a Meta rate-limit response — reduce message frequency
Session invalid	Delete ~/.openclaw/sessions/whatsapp-baileys/ and re-scan

iMessage

Problem	Solution
chat.db permission denied	Grant Full Disk Access to your terminal app
Messages delayed or missed	Reduce pollInterval to 1000 (1 second)
imessage-rest crashes	Update with pip3 install --upgrade imessage-rest
Only works locally	iMessage gateway must run on a Mac — cannot be a Linux server

---

Quick Reference

Setting	WhatsApp Business	WhatsApp Baileys	iMessage
Business account needed	Yes	No	No
Cloud server compatible	Yes	Yes	No (Mac only)
Auto-reconnects	Yes	Yes	Yes (polling)
Message delivery receipts	Yes	Yes	No
Max message size	4096 chars	Unlimited	Unlimited

---

Next: Chapter 8 — Telegram & Signal Setup — The two most developer-friendly privacy-respecting channels.