Skip to main content
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.

​
Connect a number

# 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.

​
Choose an agent runtime

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

OpenClaw

Install @kapso/openclaw-whatsapp to add WhatsApp as an OpenClaw channel.

Hermes Agent

Install gokapso/hermes-agent-plugin to receive Kapso webhooks in Hermes.

Chat SDK

Use @kapso/chat-adapter for Chat SDK agents, replies, media, and history.

MCP server

Let an MCP-capable agent operate WhatsApp without shell access.

​
OpenClaw

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 to resolve the sender number, register the webhook, and write channel config.

​
Hermes Agent

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.

​
Custom agent

Create a project API key in API & webhooks → API keys. Get the phone number ID for the number you want to use: 
kapso whatsapp numbers list --output json
Copy the id for the right number, then export both values: 
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

# 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

# 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

# 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 for the full command list. For SDK code, use @kapso/whatsapp-cloud-api. For live agent tools, use Project MCP.

Build with AI

Agent skills, llms.txt, and MCP setup for AI coding agents.

Connect WhatsApp

Compare instant setup, WhatsApp Business app, and bring your own SIM.