Channels
By openclaw-whatsapp-plugin
Install
openclaw plugins install openclaw-channel-imbee-whatsapp-officialREADME
# OpenClaw Official WhatsApp MVP
This repository contains a local-runnable MVP for:
- `backend/`: Go routing server (pairing, webhook verification, inbound forwarding, outbound send stub)
- `plugin/`: OpenClaw channel plugin (`defineChannelPluginEntry` + `createChatChannelPlugin`) with WebSocket inbound bridge
- `shared/contracts/`: API contract starter (`openapi.yaml`)
- `docs/`: PRD and technical plan
## Local run with Docker
Default host ports (see `docker-compose.yml`):
- **Backend HTTP/WS:** `http://localhost:28080` (container listens on `:8080`)
- **Postgres:** `localhost:28032` (container listens on `:5432`)
1. Copy env file:
```bash
cp .env.example .env
```
2. Start backend:
```bash
./scripts/dev-up.sh
```
3. Run smoke test:
```bash
./scripts/smoke-test.sh
```
4. Request a pairing code with Go dev CLI:
```bash
(cd backend && go run ./cmd/devcli pair --instance-id local-dev-instance)
```
5. Open a WebSocket listener (replace API key from pair response):
```bash
(cd backend && go run ./cmd/devcli ws --api-key imbee_xxx)
```
6. Replay a signed webhook event:
```bash
TEXT="CLAW-XXXX-YYYY" ./scripts/replay-webhook.sh
```
Then send a normal inbound message:
```bash
TEXT="hello from test user" ./scripts/replay-webhook.sh
```
7. Stop:
```bash
./scripts/dev-down.sh
```
## Backend endpoints
- `GET /healthz`
- `POST /api/v1/pair/request` body `{ "instanceId": "..." }`
- `GET /api/v1/pair/status` with `Authorization: Bearer <apiKey>`
- `POST /api/v1/send` with bearer token
- `GET /ws` with bearer token
- `POST /webhooks/whatsapp` with `X-Hub-Signature-256: sha256=<hmac>`
## OpenClaw plugin (SDK-aligned)
This plugin follows the layout from the OpenClaw repo: `index.ts` (full entry), `setup-entry.ts` (lightweight setup load), and `src/channel.ts` (`ChannelPlugin` object).
1. Install into your OpenClaw environment. Pick one:
**From npm or ClawHub** (after you publish; see [Publishing (npm + ClawHub)](#publishing-npm--clawhub)):
```bash
openclaw plugins install openclaw-channel-imbee-whatsapp-official
# or force ClawHub resolution:
openclaw plugins install clawhub:openclaw-channel-imbee-whatsapp-official
```
**From a git clone** (dev link, no copy):
```bash
openclaw plugins install -l ./plugin
```
2. Enable the plugin and add channel config (example keys under `channels.imbee-whatsapp-official`):
```json5
{
channels: {
"imbee-whatsapp-official": {
routingBaseUrl: "http://localhost:28080",
instanceId: "your-openclaw-instance-id",
apiKey: "imbee_…from_pair_request…",
dmPolicy: "open",
groupPolicy: "disabled",
allowFrom: ["+85260000000"]
}
}
}
```
3. Restart the gateway (`openclaw gateway restart`). When the channel account starts, the plugin opens a WebSocket to the routing server and dispatches inbound text via `dispatchInboundReplyWithBase` (same pattern as bundled channels).
**Not implemented yet:** interactive setup wizard UI for QR + `wa.me` pairing (config `apiKey` is manual for now).
### Publishing (npm + ClawHub)
OpenClaw resolves bare package names against **ClawHub first**, then **npm** ([ClawHub](https://github.com/openclaw/openclaw/blob/main/docs/tools/clawhub.md), [Building plugins](https://github.com/openclaw/openclaw/blob/main/docs/plugins/building-plugins.md)). Publishing to both is the usual path: npm holds the tarball; ClawHub indexes it for discovery and `clawhub:` installs.
1. **Choose the npm package name** in `plugin/package.json` (`name` field). The default is `openclaw-channel-imbee-whatsapp-official`. If you use a scope (for example `@your-org/...`), update install commands accordingly.
2. **Set metadata before first publish:** add `repository`, `license`, and `author` in `plugin/package.json` as required by your org. Log in to npm: `npm login`.
3. **Publish to npm** from the plugin directory:
```bash
cd plugin
npm publish --access public
```
(Use `--access public` for scoped packages; unscoped packages are public by default.)
4. **Install the ClawHub CLI** and publish the same package to the registry (browser login or token):
```bash
npm i -g clawhub
clawhub login
cd /path/to/openclaw-whatsapp-plugin # git repo root, clean commit you intend to ship
npm pack ./plugin --dry-run # optional: preview npm tarball from repo root
```
Publish from the **repo root** using an **absolute path** to `plugin/` (some `clawhub` builds treat `./plugin` as invalid and return `Path must be a folder`). Many installs also require **`--family code-plugin`** plus **`--source-repo`** and **`--source-commit`** together.
**Prerequisite:** the directory must be a **git repository** with at least one commit, and that commit should exist on GitHub under `REPO` (so the recorded `source-commit` is real). If you see `fatal: not a git repository`, run `git init`, commit, add `origin`, and `git push`, or work inside your GitHub clone instead of a plain folder copy.
```bash
PLUGIN_DIR="$(pwd)/plugin"
REPO="dearken1031/openclaw-whatsapp-plugin" # change if your GitHub repo differs
SHA="$(git rev-parse HEAD)" # must succeed; empty SHA breaks ClawHub
clawhub package publish "$PLUGIN_DIR" \
--family code-plugin \
--source-repo "$REPO" \
--source-commit "$SHA" \
--source-path plugin
```
If you are not in a git checkout yet, paste the **40-character commit SHA** from GitHub after your first push (no `SHA=$(git …)` line):
```bash
PLUGIN_DIR="$(pwd)/plugin"
REPO="dearken1031/openclaw-whatsapp-plugin"
SHA="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" # replace with real commit from github.com/.../commits
clawhub package publish "$PLUGIN_DIR" \
--family code-plugin \
--source-repo "$REPO" \
--source-commit "$SHA" \
--source-path plugin
```
If your `clawhub` errors on unknown `--source-path`, drop that flag (it defaults to repo `.`). If it does not require `--source-repo` / `--source-commit`, you can omit them and use `clawhub package publish --help` to match your CLI version.
`clawhub package publish` often has no `--dry-run`; use `npm pack ./plugin --dry-run` from the repo root (or `cd plugin && npm pack --dry-run`) instead.
After ClawHub has the package, users can run:
```bash
openclaw plugins install openclaw-channel-imbee-whatsapp-official
openclaw plugins install clawhub:[email protected]
```
Bump `version` in `plugin/package.json` and `plugin/openclaw.plugin.json` together for each release, then `npm publish` and `clawhub package publish` again.
## Notes
- Storage supports both Postgres and in-memory modes.
- Docker compose defaults to Postgres-backed storage; switch to memory via `STORE_DRIVER=memory`.
- `/api/v1/send` returns `accepted` and does not call Meta yet.
- Webhook handler validates signature, acknowledges quickly, then routes messages in-process.
- `backend/cmd/devcli` provides local pair/ws/send workflow for plugin-side testing.
channels
Comments
Sign in to leave a comment