Channel Kapso

Name: Channel Kapso
Rating: 3.5 (1 reviews)
Author: overcut-ai

By overcut-ai 👁 14 views ▲ 0 votes

OpenClaw channel plugin for Kapso WhatsApp (Business API)

GitHub

Install

npm install

#

Configuration Example

{
  "plugins": {
    "enabled": true,
    "allow": ["kapso-whatsapp"]
  },
  "channels": {
    "kapso-whatsapp": {
      "apiKey": "YOUR_KAPSO_API_KEY",
      "phoneNumberId": "YOUR_KAPSO_PHONE_NUMBER_ID",
      "webhookSecret": "YOUR_HMAC_SECRET",
      "webhookVerifyToken": "any-random-string-you-choose",
      "dmPolicy": "allowlist",
      "allowFrom": ["+972501234567"]
    }
  }
}

README

# openclaw-channel-kapso

OpenClaw channel plugin for WhatsApp via [Kapso](https://kapso.io) — official Meta Cloud API, real-time webhook delivery.

## Why this exists

The community bridge (`openclaw-kapso-whatsapp`) connects as an external operator client, which requires `operator.write` scope. OpenClaw 2026.3.x won't grant that scope without a paired device identity — a flow the bridge hasn't implemented yet. This plugin runs *inside* OpenClaw as a first-party channel extension, bypassing that entirely.

## How it works

```
WhatsApp user
    ↓  (Kapso webhook → POST /kapso-whatsapp/webhook/default)
OpenClaw gateway  ←  this plugin registers the route
    ↓
Draft agent processes the message
    ↓
plugin calls Kapso API → message delivered to WhatsApp user
```

Real-time. No polling. No external process.

## Requirements

- OpenClaw ≥ 2026.3.14
- Kapso account with a connected WhatsApp Business number
- A public URL for webhook delivery (Tailscale Funnel, domain, or ngrok for dev)

## Install

On the VM where OpenClaw is running:

```bash
# Clone the plugin
git clone https://github.com/overcut-ai/openclaw-channel-kapso.git ~/.openclaw/plugins/kapso-whatsapp
cd ~/.openclaw/plugins/kapso-whatsapp
npm install

# Install into OpenClaw
openclaw plugins install -l ~/.openclaw/plugins/kapso-whatsapp

# Restart gateway
systemctl --user restart openclaw-gateway.service
```

## Configure

Add to `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "enabled": true,
    "allow": ["kapso-whatsapp"]
  },
  "channels": {
    "kapso-whatsapp": {
      "apiKey": "YOUR_KAPSO_API_KEY",
      "phoneNumberId": "YOUR_KAPSO_PHONE_NUMBER_ID",
      "webhookSecret": "YOUR_HMAC_SECRET",
      "webhookVerifyToken": "any-random-string-you-choose",
      "dmPolicy": "allowlist",
      "allowFrom": ["+972501234567"]
    }
  }
}
```

| Field | Required | Description |
|---|---|---|
| `apiKey` | Yes | Kapso API key (Settings → API Keys) |
| `phoneNumberId` | Yes | Kapso phone number ID |
| `webhookSecret` | Recommended | HMAC secret for signature verification |
| `webhookVerifyToken` | Yes | Token you set in Kapso webhook config |
| `dmPolicy` | No | `allowlist` (default) or `open` |
| `allowFrom` | If allowlist | E.164 phone numbers allowed to message the agent |

## Set up the webhook in Kapso

Your OpenClaw gateway needs to be reachable publicly. The webhook path is:

```
https://YOUR_DOMAIN/kapso-whatsapp/webhook/default
```

In the Kapso dashboard → your phone number → Webhooks:
- **URL:** `https://YOUR_DOMAIN/kapso-whatsapp/webhook/default`
- **Verify token:** same value as `webhookVerifyToken` in config
- **Secret:** same value as `webhookSecret` in config
- **Events:** Messages

### Expose OpenClaw with Tailscale Funnel (recommended)

```bash
# On the VM
tailscale funnel 443 on
# Your URL will be https://<machine-name>.tail<id>.ts.net
```

### Or open port 443 in the NSG (alternative)

Add an inbound rule to `oc-claw-nsg` allowing TCP 443 from any source, then point a domain at the VM IP.

## Test

```bash
# Verify plugin is loaded
openclaw plugins list

# Check gateway logs
journalctl --user -u openclaw-gateway.service -f

# Send a WhatsApp message to your number — it should reach the agent
```

## Multiple accounts

To connect multiple WhatsApp numbers:

```json
{
  "channels": {
    "kapso-whatsapp": {
      "accounts": {
        "main": {
          "apiKey": "KEY_1",
          "phoneNumberId": "ID_1",
          "allowFrom": ["+972501234567"]
        },
        "support": {
          "apiKey": "KEY_2",
          "phoneNumberId": "ID_2",
          "dmPolicy": "open"
        }
      }
    }
  }
}
```

Webhook paths will be `/kapso-whatsapp/webhook/main` and `/kapso-whatsapp/webhook/support`.

channels