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

# Personal AI agents

> Give your AI agent a WhatsApp number.

Use Kapso when you want a personal agent to send and receive WhatsApp messages from a real number.

## What you need

* A Kapso project
* A connected WhatsApp number
* A project API key
* An agent runtime connected through OpenClaw, Hermes Agent, Chat SDK, MCP, or your own webhook

If your number is already connected, skip to [choose an agent runtime](#choose-an-agent-runtime).

## Connect a number

```bash theme={null}
# install the CLI
curl -fsSL https://kapso.ai/install.sh | bash

# connect a number
kapso setup

# check your numbers
kapso whatsapp numbers list
```

For other connection paths, see [Connect WhatsApp](/docs/how-to/whatsapp/connect-whatsapp).

## Choose an agent runtime

Use a native integration when your agent already runs on one of these runtimes:

<CardGroup cols={2}>
  <Card title="OpenClaw" icon="plug" href="/docs/whatsapp/openclaw">
    Install `@kapso/openclaw-whatsapp` to add WhatsApp as an OpenClaw channel.
  </Card>

  <Card title="Hermes Agent" icon="bolt" href="/docs/whatsapp/hermes-agent">
    Install `gokapso/hermes-agent-plugin` to receive Kapso webhooks in Hermes.
  </Card>

  <Card title="Chat SDK" icon="message" href="/docs/whatsapp/chat-sdk">
    Use `@kapso/chat-adapter` for Chat SDK agents, replies, media, and history.
  </Card>

  <Card title="MCP server" icon="server" href="/docs/whatsapp/mcp">
    Let an MCP-capable agent operate WhatsApp without shell access.
  </Card>
</CardGroup>

### OpenClaw

```bash theme={null}
openclaw plugins install clawhub:@kapso/openclaw-whatsapp
openclaw config set 'plugins.allow' '["codex","kapso-whatsapp"]' --strict-json
openclaw config set 'channels["kapso-whatsapp"].enabled' true --strict-json
```

Then run the setup command from the [OpenClaw guide](/docs/whatsapp/openclaw) to resolve the sender number, register the webhook, and write channel config.

### Hermes Agent

```bash theme={null}
hermes plugins install gokapso/hermes-agent-plugin --enable
hermes kapso setup --install-cli --funnel-url https://<your-funnel-host>
hermes gateway restart
```

The setup command can install the Kapso CLI, pick the WhatsApp number, generate the webhook secret, and create the Kapso webhook. See the [Hermes Agent guide](/docs/whatsapp/hermes-agent).

## Custom agent

Create a project API key in **Integrations → API keys**.

Get the phone number ID for the number you want to use:

```bash theme={null}
kapso whatsapp numbers list --output json
```

Copy the `id` for the right number, then export both values:

```bash theme={null}
export KAPSO_API_KEY="your_project_api_key"
export KAPSO_PHONE_NUMBER_ID="your_phone_number_id"
```

With these values, your agent can call the CLI, the TypeScript SDK, the WhatsApp API proxy, or Project MCP.

### Send messages

```bash theme={null}
# send a text message
kapso whatsapp messages send \
  --phone-number-id $KAPSO_PHONE_NUMBER_ID \
  --to "+1234567890" \
  --text "Your order has shipped"

# send a JSON payload (media, interactive, templates)
kapso whatsapp messages send \
  --phone-number-id $KAPSO_PHONE_NUMBER_ID \
  --input message.json
```

### Read conversations

```bash theme={null}
# list recent conversations
kapso whatsapp conversations list --phone-number-id $KAPSO_PHONE_NUMBER_ID

# list inbound messages
kapso whatsapp messages list \
  --phone-number-id $KAPSO_PHONE_NUMBER_ID \
  --direction inbound \
  --limit 20
```

### Set up webhooks

```bash theme={null}
# receive messages via webhook
kapso whatsapp webhooks new \
  --phone-number-id $KAPSO_PHONE_NUMBER_ID \
  --url "https://your-agent.example.com/webhook" \
  --event whatsapp.message.received \
  --active
```

All commands support `--output json` for structured parsing. See the [CLI reference](/docs/whatsapp/cli) for the full command list.

For SDK code, use [`@kapso/whatsapp-cloud-api`](/docs/whatsapp/typescript-sdk/introduction). For live agent tools, use [Project MCP](/docs/whatsapp/mcp).

<CardGroup cols={2}>
  <Card title="Build with AI" icon="microchip" href="/docs/build-with-ai">
    Agent skills, llms.txt, and MCP setup for AI coding agents.
  </Card>

  <Card title="Connect WhatsApp" icon="message" href="/docs/how-to/whatsapp/connect-whatsapp">
    Compare instant setup, WhatsApp Business app, and bring your own SIM.
  </Card>
</CardGroup>