> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openpawz.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp

> Give your agent a WhatsApp number. People message that number, your agent replies — all on your machine.

# WhatsApp

Give your agent a WhatsApp number. People message that number, your agent replies — all on your machine.

:::warning Important — read this first
When you scan the QR code, **that phone number becomes your agent**. Anyone who messages that number will be talking to your AI — not you.

**Do not use your personal number** unless you specifically want your agent handling all your WhatsApp conversations.
:::

## You need a separate phone number

Pawz connects to WhatsApp the same way WhatsApp Web does — by linking to an existing account. It can't create new phone numbers. The number you scan is the number people will message to talk to your agent.

### Recommended: get a cheap prepaid SIM

1. Buy a prepaid SIM card (\~\$5 at any store or online)
2. Register WhatsApp on it (use an old phone, or briefly swap SIMs)
3. You only need the SIM active long enough to receive the verification SMS
4. After linking, WhatsApp stays connected even if the SIM expires

Other options:

* **eSIM** (Airalo, etc.) — \~\$5, activate on your phone
* **Google Voice** — free but WhatsApp often rejects VoIP numbers
* **Second phone** with its own number

## Setup

1. In Pawz, go to **Settings → Channels**
2. Select **WhatsApp**
3. Choose who can message your agent (defaults are fine to start)
4. Click **Save & Connect**
5. A QR code will appear — **scan it from the agent's phone** (the one with the separate number)
   * WhatsApp → Settings → Linked Devices → Link a Device
6. Done! People can now message that number to talk to your agent

## What happens when someone messages

```mermaid actions={false} theme={null}
graph TD
    A["Someone messages\nthe agent's number"] --> B["Pawz receives it\nvia local webhook"]
    B --> C["Access control checks\nPairing / Allowlist / Open"]
    C --> D["Agent processes\nthe message"]
    D --> E["Reply sent back\nto WhatsApp"]
```

All traffic stays on your machine. Nothing is exposed to the internet.

## Access control

| Mode                  | Behavior                                                           |
| --------------------- | ------------------------------------------------------------------ |
| **Pairing** (default) | New contacts get "waiting for approval" — you approve/deny in Pawz |
| **Open**              | Anyone can message the agent immediately                           |
| **Allowlist**         | Only pre-approved phone numbers can message                        |

When using **Pairing** mode, pending requests show up on the WhatsApp channel card in Pawz with Approve / Deny buttons.

## Configuration

| Setting                     | Description                                           |
| --------------------------- | ----------------------------------------------------- |
| Who can message your agent? | Pairing / Open / Allowlist                            |
| Reply in group chats too    | Whether the agent responds in groups (default: off)   |
| Allowed phone numbers       | Only needed for allowlist mode — include country code |
| Agent                       | Leave blank for default, or pick a specific agent     |

## Features

* QR code authentication (scan to link)
* Direct messages and group chat support
* Per-user conversation sessions with memory
* Prompt injection scanning on all incoming messages
* Agent routing via channel routing rules
* Auto-approval of tool calls (no human-in-the-loop for channel messages)
* Everything runs locally — nothing exposed to the internet

## Tips

* The QR code expires after a few minutes — scan it promptly
* If you lose connection, click Stop then Start to get a fresh QR code
* Phone numbers in allowlist should include country code (e.g., `15551234567`)
* The agent uses WhatsApp formatting: *bold*, *italic*, ~~strikethrough~~, \`\`\`code\`\`\`
* Long responses are automatically split into multiple messages