# WhatsApp Channel

## Overview

OpenClaw's WhatsApp integration via Baileys where the gateway owns the session(s). The setup enables multiple WhatsApp accounts within a single gateway process with deterministic message routing.

## Quick Start

Requirements:

- A separate phone number (recommended)
- Configuration in `~/.openclaw/openclaw.json`
- Running `openclaw channels login` to scan a QR code
- An active listener for sending messages

## Operating Modes

### Dedicated Number Approach (Preferred)

Use a separate device with an eSIM to keep operations isolated from personal contacts. This avoids "self-chat quirks" and provides cleaner routing.

### Personal Number Fallback

Run OpenClaw on your own WhatsApp account by enabling `selfChatMode`, though this requires messaging yourself to test without spamming contacts.

## Access Control

The platform implements a pairing-based gating system for unknown senders. The first direct message from a new sender returns a short code (message is not processed). Users then approve access using:

```bash
openclaw pairing approve whatsapp <code>
```

Codes expire after one hour, with a maximum of three pending requests per channel.

## Message Handling

### Quoted Replies

Include full context, appended as `[Replying to +1555 id:ABC123]` followed by the quoted content.

### Media-Only Messages

Use placeholders like `<media:image|video|audio|document|sticker>`.

## Groups & History

- Group messages require mentions or regex matching by default
- Recent unprocessed messages (up to 50) are injected for context
- Context messages are labeled with sender information and marked as "for context" to distinguish them from current messages

## Acknowledgment Reactions

Emoji reactions provide immediate receipt feedback before bot replies generate. Configuration allows customizing the emoji and limiting reactions to:

- Direct chats
- Group mentions
- All group messages

## Technical Limits

| Limit | Default |
|-------|---------|
| Outbound text | 4,000 character chunks (configurable) |
| Inbound media | 50 MB default cap |
| Outbound media | 5 MB per item default |

Images auto-optimize to JPEG within limits.