diff --git a/README.md b/README.md index 0c35918bb..85245c701 100644 --- a/README.md +++ b/README.md @@ -1,133 +1,114 @@ -# 📡 warelay — WhatsApp Relay CLI (Twilio) +# 📡 warelay — WhatsApp Relay CLI -Small TypeScript CLI to send, receive, auto-reply, and inspect WhatsApp messages via Twilio. Works in polling mode or webhook mode (with Tailscale Funnel helper). +Small CLI to send, receive, auto-reply, and inspect WhatsApp messages over **Twilio** or your personal **WhatsApp Web** session. Ships with a one-command webhook setup (Tailscale Funnel + Twilio callback) and a configurable auto-reply engine (plain text or command/Claude driven). -You can also talk to WhatsApp directly with a personal WhatsApp Web session (QR login) via `--provider web`—no Twilio needed for send/receive in that mode. +## Quick Start (5 steps) +1) Prereqs: Node 22+, `pnpm`, a Twilio account with a WhatsApp-enabled number; Tailscale optional for webhooks. +2) Install deps: `pnpm install` +3) Copy `.env.example` → `.env`; set `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` **or** `TWILIO_API_KEY`/`TWILIO_API_SECRET`, and `TWILIO_WHATSAPP_FROM=whatsapp:+15551234567` (plus optional `TWILIO_SENDER_SID`). +4) Send a test: `pnpm warelay send --to +12345550000 --message "Hi from warelay"` +5) Choose how to receive replies: + - Polling (no ingress): `pnpm warelay relay --provider twilio --interval 5 --lookback 10` + - Webhook (automatic): `pnpm warelay up --port 42873 --path /webhook/whatsapp --verbose` + - Personal WhatsApp (no Twilio): `pnpm warelay web:login` then `pnpm warelay send --provider web ...` -## What it can do +## Main Features +- **Two providers:** Twilio (default) for reliable delivery + status; Web provider for quick personal sends/receives via QR login. +- **Auto-replies:** Static templates or external commands (Claude-aware), with per-sender or global sessions and `/new` resets. +- **Webhook in one go:** `warelay up` enables Tailscale Funnel, runs the webhook server, and updates the Twilio sender callback URL. +- **Polling fallback:** `relay` polls Twilio when webhooks aren’t available; works headless. +- **Status + delivery tracking:** `status` shows recent inbound/outbound; `send` can wait for final Twilio status. -- Send and track delivery for WhatsApp messages over Twilio. -- Auto-reply via webhook or polling, with Claude-backed command replies or simple text templates. -- Run entirely on your personal WhatsApp Web session (`--provider web`) for direct messaging without Twilio. -- One-shot `up` command to launch webhook server, publish via Tailscale Funnel, and point Twilio callbacks automatically. +## Command Cheat Sheet +| Command | What it does | Core flags | +| --- | --- | --- | +| `warelay send` | Send a WhatsApp message (Twilio or Web) | `--to ` `--message ` `--wait ` `--poll ` `--provider twilio|web` `--json` `--dry-run` | +| `warelay relay` | Auto-reply loop (poll Twilio or listen on Web) | `--provider auto|twilio|web` `--interval ` `--lookback ` `--verbose` | +| `warelay status` | Show recent sent/received messages | `--limit ` `--lookback ` `--json` | +| `warelay webhook` | Run local inbound webhook server | `--port ` `--path ` `--reply ` `--verbose` `--yes` `--dry-run` | +| `warelay up` | Turn on webhook + Tailscale Funnel + Twilio callback | `--port ` `--path ` `--verbose` `--yes` `--dry-run` | +| `warelay web:login` (`login`) | Link personal WhatsApp Web via QR | `--verbose` | -## Quick Start +## Providers +- **Twilio (default):** needs `.env` creds + WhatsApp-enabled number; supports delivery tracking, polling, webhooks, and auto-reply typing indicators. +- **Web (`--provider web`):** uses your personal WhatsApp via Baileys; supports send/receive + auto-reply, but no delivery-status wait; cache lives in `~/.warelay/credentials/` (rerun `web:login` if logged out). +- **Auto-select (`relay` only):** `--provider auto` uses Web when logged in, otherwise Twilio polling. -1) Install: `pnpm install` -2) Configure `.env` (see `.env.example`): set `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` (or `TWILIO_API_KEY`/`TWILIO_API_SECRET`), and `TWILIO_WHATSAPP_FROM=whatsapp:+15551234567`. Optional: `TWILIO_SENDER_SID` if you don’t want auto-discovery. -3) Send a test (Twilio): `pnpm warelay send --to +12345550000 --message "Hi from warelay"` - Dry run without sending: `pnpm warelay send --to +12345550000 --message "Hi" --dry-run` - Send direct via personal WhatsApp: `pnpm warelay web:login` (scan QR once) then `pnpm warelay send --provider web --to +12345550000 --message "Hi from warelay"` -4) Run auto-replies in polling mode (no public URL needed): - `pnpm warelay relay --provider twilio --interval 5 --lookback 10 --verbose` -5) Prefer webhooks? Launch everything in one step (webhook + Tailscale Funnel + Twilio callback): - `pnpm warelay up --port 42873 --path /webhook/whatsapp --verbose` +## Configuration -## Modes at a Glance +### Environment (.env) +| Variable | Required | Description | +| --- | --- | --- | +| `TWILIO_ACCOUNT_SID` | Yes (Twilio provider) | Twilio Account SID | +| `TWILIO_AUTH_TOKEN` | Yes* | Auth token (or use API key/secret) | +| `TWILIO_API_KEY` | Yes* | API key if not using auth token | +| `TWILIO_API_SECRET` | Yes* | API secret paired with `TWILIO_API_KEY` | +| `TWILIO_WHATSAPP_FROM` | Yes (Twilio provider) | WhatsApp-enabled sender, e.g. `whatsapp:+15551234567` | +| `TWILIO_SENDER_SID` | Optional | Overrides auto-discovery of the sender SID | -- **Polling (`relay --provider twilio`)**: Periodically fetch inbound messages to your WhatsApp number. Easiest to start; no ingress needed. Auto-replies still run. -- **Webhook (`webhook` / `up`)**: Push delivery from Twilio. `webhook` runs the server locally; `up` also enables Tailscale Funnel and points the Twilio sender/webhook to your public Funnel URL (with fallbacks to phone number and messaging service). +(*Provide either auth token OR api key/secret.) -## Providers (choose per command) +### Auto-reply config (`~/.warelay/warelay.json`, JSON5) +- Controls who is allowed to trigger replies (`allowFrom`), reply mode (`text` or `command`), templates, and session behavior. +- Example (Claude command): -- **Twilio (default)** — full feature set: send, wait/poll delivery, status, inbound polling/webhook, auto-replies. Requires `.env` Twilio creds and a WhatsApp-enabled number (`TWILIO_WHATSAPP_FROM`). -- **Web (`--provider web`)** — direct messaging through your personal WhatsApp account (no Twilio). Supports outbound sends and inbound auto-replies when you run `pnpm warelay relay --provider web`. No delivery-status polling for web sends (WhatsApp Web doesn’t expose it). Setup: `pnpm warelay web:login` (alias: `pnpm warelay login`) then either send with `--provider web` or keep `relay --provider web` running. Session data lives in `~/.warelay/credentials.json`; if logged out, rerun `web:login`/`login`. Use at your own risk (personal-account automation can be rate-limited or logged out by WhatsApp). - -## Common Commands - -- Send: `pnpm warelay send --to +12345550000 --message "Hello" --wait 20 --poll 2` -- Send (JSON output): `pnpm warelay send --to +12345550000 --message "Hello" --json` -- Send via personal WhatsApp Web: first `pnpm warelay web:login` (alias: `pnpm warelay login`, scan QR), then `pnpm warelay send --provider web --to +12345550000 --message "Hi"` -- Auto-replies (auto provider): `pnpm warelay relay` (uses web if logged in, otherwise twilio poll) -- Auto-replies (force web): `pnpm warelay relay --provider web` -- Auto-replies (force Twilio poll): `pnpm warelay relay --provider twilio --interval 5 --lookback 10 --verbose` -- Webhook only: `pnpm warelay webhook --port 42873 --path /webhook/whatsapp --verbose` -- Webhook + Funnel + Twilio update: `pnpm warelay up --port 42873 --path /webhook/whatsapp --verbose` -- Status (recent sent/received): `pnpm warelay status --limit 20 --lookback 240` (add `--json` for machine-readable) - -## Auto-Reply Config (JSON5 at `~/.warelay/warelay.json`) - -### Claude-style example (your current setup) ```json5 { inbound: { - allowFrom: ["***REMOVED***"], // optional allowlist (E.164, no whatsapp: prefix) + allowFrom: ["+12345550000"], reply: { mode: "command", - bodyPrefix: "You are a helpful assistant running on the user's Mac. User writes messages via WhatsApp and you respond. You want to be concise in your responses, at most 1000 characters.\n\n", - command: [ - "claude", - "--dangerously-skip-permissions", - "{{BodyStripped}}" - ], - claudeOutputFormat: "text", // forces --output-format text and adds -p/--print when missing - session: { - scope: "per-sender", - resetTriggers: ["/new"], - idleMinutes: 60, - sessionArgNew: ["--session-id", "{{SessionId}}"], - sessionArgResume: ["--resume", "{{SessionId}}"], - sessionArgBeforeBody: true - } + bodyPrefix: "You are a concise WhatsApp assistant.\n\n", + command: ["claude", "--dangerously-skip-permissions", "{{BodyStripped}}"], + claudeOutputFormat: "text", + session: { scope: "per-sender", resetTriggers: ["/new"], idleMinutes: 60 } } } } ``` -### Claude CLI integration +### Claude CLI setup (how we run it) +1) Install the official Claude CLI (e.g., `brew install anthropic-ai/cli/claude` or follow the Anthropic docs) and run `claude login` so it can read your API key. +2) In `warelay.json`, set `reply.mode` to `"command"` and point `command[0]` to `"claude"`; set `claudeOutputFormat` to `"text"` (or `"json"/`"stream-json"` if you want warelay to parse and trim the JSON output). +3) (Optional) Add `bodyPrefix` to inject a system prompt and `session` settings to keep multi-turn context (`/new` resets by default). +4) Run `pnpm warelay relay --provider auto` (or `--provider web|twilio`) and send a WhatsApp message; warelay will queue the Claude call, stream typing indicators (Twilio provider), parse the result, and send back the text. -- When `command[0]` is `claude`, set `claudeOutputFormat` to `"text"`, `"json"`, or `"stream-json"` and warelay will inject `--output-format` and `-p/--print` automatically. -- For `"json"`/`"stream-json"`, warelay parses Claude's JSON payload and sends just the text content to WhatsApp while keeping the full JSON in logs for debugging. -- If you omit `claudeOutputFormat`, warelay leaves your args untouched (useful for custom Claude flags). -- The config loader validates `warelay.json` (mode/text/command/claudeOutputFormat/session shape) and logs warnings for invalid combos instead of failing later at runtime. - -### Running without Twilio (personal WhatsApp Web) - -- Log in once: `pnpm warelay web:login` (or `pnpm warelay login`), scan the QR in your terminal/browser. Credentials are stored locally at `~/.warelay/credentials.json`. -- Send: `pnpm warelay send --provider web --to +12345550000 --message "Hi"`. -- Auto-reply loop: `pnpm warelay relay --provider web --interval 5 --lookback 10`. Typing indicators are skipped in this mode, but text replies still work. -- You can mix modes: use Twilio for reliable delivery/status, switch to web for quick personal sends. Each command decides the provider independently. - -### Simple text echo -```json5 -{ - inbound: { - reply: { mode: "text", text: "Echo: {{Body}}" } - } -} -``` - -Notes: -- Templates support `{{Body}}`, `{{BodyStripped}}`, `{{From}}`, `{{To}}`, `{{MessageSid}}`, plus `{{SessionId}}`/`{{IsNewSession}}` when session reuse is enabled. -- `/new` (or any `resetTriggers` value) resets the session. `/new ask…` resets and sends `ask…` as the prompt (via `BodyStripped`). -- When an auto-reply starts (text or command), warelay sends a WhatsApp typing indicator tied to the inbound `MessageSid`. - -## Troubleshooting Delivery - -- Auto-reply send failures now print in red with Twilio code/status and the response body (e.g., policy violation 63112). Watch terminal output when running `relay`, `webhook`, or `up`. -- Check recent messages: `pnpm warelay status --limit 20 --lookback 240`. -- If you must resend while a reply is long-running, keep messages <1600 chars (WhatsApp limit) and avoid restricted content/templates. - -## Options Reference - -| Field | Type / Values | Default | Description | +### Auto-reply parameter table +| Key | Type | Default | Notes | | --- | --- | --- | --- | -| `inbound.allowFrom` | `string[]` | empty | Allowlist of E.164 numbers (no `whatsapp:`). If set, only these trigger auto-replies. | -| `inbound.reply.mode` | `"text"` \| `"command"` | — | Auto-reply type. | -| `inbound.reply.text` | `string` | — | Reply body for text mode; templated. | -| `inbound.reply.command` | `string[]` | — | Argv to run for command mode; templated per element. Stdout (trimmed) is sent. | -| `inbound.reply.template` | `string` | — | Optional string inserted as second argv element (prompt prefix). | -| `inbound.reply.bodyPrefix` | `string` | — | Prepends to `Body` before templating (ideal for system instructions). | -| `inbound.reply.session.scope` | `"per-sender" \| "global"` | `per-sender` | Session key: one per sender or single global chat. | -| `inbound.reply.session.resetTriggers` | `string[]` | `["/new"]` | Any entry acts as both exact reset token and prefix (`/new hi`). | -| `inbound.reply.session.idleMinutes` | `number` | `60` | Expire and recreate session after this idle time. | -| `inbound.reply.session.sessionArgNew` | `string[]` | `["--session-id","{{SessionId}}"]` | Args inserted for a new session run. | -| `inbound.reply.session.sessionArgResume` | `string[]` | `["--resume","{{SessionId}}"]` | Args inserted when resuming an existing session. | -| `inbound.reply.session.sessionArgBeforeBody` | `boolean` | `true` | Place session args before the final body argument. | -| `inbound.reply.claudeOutputFormat` | `"text" \| "json" \| "stream-json"` | — | When `command[0]` is `claude`, force this output format and auto-add `-p/--print` so Claude exits after emitting output. | -| `inbound.reply.timeoutSeconds` | `number` | 600 | Command timeout. | +| `inbound.allowFrom` | `string[]` | empty | E.164 numbers allowed to trigger auto-reply (no `whatsapp:`). | +| `inbound.reply.mode` | `"text" | "command"` | — | Reply style. | +| `inbound.reply.text` | `string` | — | Used when `mode=text`; templating supported. | +| `inbound.reply.command` | `string[]` | — | argv for `mode=command`; each element templated. Stdout (trimmed) is sent. | +| `inbound.reply.template` | `string` | — | Injected as argv[1] (prompt prefix) before the body. | +| `inbound.reply.bodyPrefix` | `string` | — | Prepended to `Body` before templating (great for system prompts). | +| `inbound.reply.timeoutSeconds` | `number` | `600` | Command timeout. | +| `inbound.reply.claudeOutputFormat` | `"text"|"json"|"stream-json"` | — | When command starts with `claude`, auto-adds `--output-format` + `-p/--print` and trims reply text. | +| `inbound.reply.session.scope` | `"per-sender"|"global"` | `per-sender` | Session bucket for conversation memory. | +| `inbound.reply.session.resetTriggers` | `string[]` | `["/new"]` | Exact match or prefix (`/new hi`) resets session. | +| `inbound.reply.session.idleMinutes` | `number` | `60` | Session expires after idle period. | +| `inbound.reply.session.store` | `string` | `~/.warelay/sessions.json` | Custom session store path. | +| `inbound.reply.session.sessionArgNew` | `string[]` | `["--session-id","{{SessionId}}"]` | Args injected for a new session run. | +| `inbound.reply.session.sessionArgResume` | `string[]` | `["--resume","{{SessionId}}"]` | Args for resumed sessions. | +| `inbound.reply.session.sessionArgBeforeBody` | `boolean` | `true` | Place session args before final body arg. | -## Dev Notes +Templating tokens: `{{Body}}`, `{{BodyStripped}}`, `{{From}}`, `{{To}}`, `{{MessageSid}}`, plus `{{SessionId}}` and `{{IsNewSession}}` when sessions are enabled. -- During dev you can run without building: `pnpm dev -- ` (e.g., `pnpm dev -- send --to +1...`). -- Stop relay/webhook with `Ctrl+C`. CLI uses `pnpm` and `tsx`; no build required for local runs. +## Webhook & Tailscale Flow +- `warelay webhook` starts the local Express server on your chosen port/path; add `--reply "Got it"` for a static reply when no config file is present. +- `warelay up` adds Funnel: checks `tailscale`, enables `tailscale funnel `, prints the public URL (`https://`), starts the webhook, discovers the WhatsApp sender SID, and updates Twilio callbacks to the Funnel URL. +- If Funnel is not allowed on your tailnet, the CLI exits with guidance; you can still use `relay --provider twilio` to poll without webhooks. + +## Troubleshooting Tips +- Send/receive issues: run `pnpm warelay status --limit 20 --lookback 240 --json` to inspect recent traffic. +- Auto-reply not firing: ensure sender is in `allowFrom` (or unset), and confirm `.env` + `warelay.json` are loaded (reload shell after edits). +- Web provider dropped: rerun `pnpm warelay web:login`; credentials live in `~/.warelay/credentials/`. +- Tailscale Funnel errors: update tailscale/tailscaled; check admin console that Funnel is enabled for this device. + +## FAQ & Safety (quick answers) +- Twilio errors: **63016 “permission to send an SMS has not been enabled”** → ensure your number is WhatsApp-enabled; **63007 template not approved** → send a free-form session message within 24h or use an approved template; **63112 policy violation** → adjust content, shorten to <1600 chars, avoid links that trigger spam filters. Re-run `pnpm warelay status` to see the exact Twilio response body. +- Does this store my messages? Warelay only writes `~/.warelay/warelay.json` (config), `~/.warelay/credentials/` (WhatsApp Web auth), and `~/.warelay/sessions.json` (session IDs + timestamps). It does **not** persist message bodies beyond the session store. Logs print to stdout/stderr; redirect or rotate if needed. +- Personal WhatsApp safety: Automation on personal accounts can be rate-limited or logged out by WhatsApp. Use `--provider web` sparingly, keep messages human-like, and re-run `web:login` if the session is dropped. +- Limits to remember: WhatsApp text limit ~1600 chars; avoid rapid bursts—space sends by a few seconds; keep webhook replies under a couple seconds for good UX; command auto-replies time out after 600s by default. +- Deploy / keep running: Use `tmux` or `screen` for ad-hoc (`tmux new -s warelay -- pnpm warelay relay --provider twilio`). For long-running hosts, wrap `pnpm warelay relay ...` or `pnpm warelay up ...` in a systemd service or macOS LaunchAgent; ensure environment variables are loaded in that context. +- Rotating credentials: Update `.env` (Twilio keys), rerun your process; for Web provider, delete `~/.warelay/credentials/` and rerun `pnpm warelay web:login` to relink.