The Wassist CLI is the fastest way to test agents and webhooks without leaving your terminal. It uses your existing Wassist account and the same /api/v1 endpoints as the dashboard.
The CLI requires Node.js 22+ (it uses the built-in WebSocket global). See the GitHub source or @wassist/cli on npm. Install
npm install -g @wassist/cli
Authenticate
You’ll be prompted for your phone number, then a 6-digit code arrives on WhatsApp from the Wassist sandbox number — the same number you’ll send test messages to in a moment.
Confirm you’re signed in:
After login the CLI is automatically scoped to your sandbox conversation — a one-on-one chat between your personal WhatsApp and the Wassist sandbox number. Sandbox mode means most commands don’t need a [to-number] argument.
Switch between sandbox and a real WhatsApp number any time with wassist use sandbox or wassist use <your-number>.
Sending messages
WhatsApp only lets you send free-form messages inside an active 24-hour customer-care window. Before your first messages send, either message the Wassist sandbox number from your phone to open the window, or send a pre-approved template message (see Outside the 24-hour window below). messages send command supports the full WhatsApp message envelope — text, media, buttons, and footers — composed via flags.
Text
With media
Quick replies
URL button
wassist messages send "Hello from the CLI"
wassist messages send "Check this out" \
--media https://picsum.photos/200/300
wassist messages send "Choose one" \
--reply "Yes|confirm" \
--reply "No|deny"
wassist messages send "Visit us" \
--url-button "Shop Now|https://shop.com"
Validation rules
- Text body — max 1024 characters.
- Buttons — max 3 total, all the same type.
- Media — must be a publicly reachable HTTPS URL.
- Button labels — max 20 characters, formatted
"Label|value".
Outside the 24-hour window
If the conversation’s customer-care 24-hour window has lapsed (no inbound user message in the last 24 hours), the CLI prompts you to pick a pre-approved template instead — the same constraint as the WhatsApp Business API enforces directly.
Streaming inbound messages
messages listen opens a WebSocket session, so every inbound WhatsApp message lands in your terminal in real time. Behind the scenes Wassist creates a managed webhook for this session and tunnels it through a WebSocket relay — you don’t need to expose a public URL.
wassist messages listen --interactive
─── wassist messages listen ──────────────────────────────
[10:24] customer +447700900200
Hey, can I add another item to my order?
> Sure! What would you like to add?
> prompt accepts the same --media, --url-button, and --reply flags as messages send:
> Here's a photo --media https://picsum.photos/300 --reply "Looks good|yes" --reply "Try another|no"
messages listen is ideal when you’re iterating on an agent or a webhook handler and want to see events the instant they arrive. It runs alongside your own webhooks — both fire on every inbound message.
Combining the CLI with webhooks
A common dev loop:
- Configure your own webhook in the dashboard pointing at your local dev server (via your tunneling tool of choice — ngrok, Cloudflare Tunnel, Tailscale Funnel, etc.).
- In another terminal, run
wassist messages listen so you can watch inbound messages while your webhook is processing them.
- Send a test event from the dashboard (wassist.app/developers/webhooks → your webhook → Send test event) or send a real message from your phone.
- Inspect the delivery in Developers → Webhooks → Deliveries for the full request/response timeline, or click Replay to re-send it without retyping anything on WhatsApp.
See the developer quickstart for an end-to-end walkthrough.
Moving to your own number
The sandbox is great for development. To message real contacts, connect a WhatsApp Business number:
Upgrade your plan
A Wassist subscription is required to connect your own number. Link your WhatsApp Business Account
Opens Meta’s embedded signup in your browser so you can pick (or claim) a phone number. Switch to your number
wassist numbers list # see numbers you can use
wassist use 441234567890 # set the active number
Send messages to real contacts
With your own number active, include the recipient’s E.164 number:wassist messages send 441234567890 "Hey, this is from my own number!"
wassist messages read 441234567890
wassist use sandbox.
Command reference
Authentication
| Command | Description |
|---|
wassist login | Authenticate via WhatsApp OTP. |
wassist whoami | Show the authenticated user and current plan. |
Number management
| Command | Description |
|---|
wassist use <number> | Set the active number. Use sandbox to switch back to the shared sandbox. |
wassist numbers list | List all WhatsApp numbers, marking the active one. |
wassist numbers add | Add a new WhatsApp number (Starter plan or above). |
Messaging
In sandbox mode the phone-number argument is optional — the CLI resolves your single sandbox conversation automatically.
| Command | Description |
|---|
wassist messages list | List conversations for the active number. |
wassist messages read [phone-number] | View messages for a contact. Flags: --limit <n>, --page <n>. |
wassist messages send [to-number] [message] | Send a message. Flags: --footer, --media, --url-button, --reply (repeatable). |
wassist messages listen [phone-number] | Stream inbound messages over WebSocket. Flag: -i / --interactive for inline replies. |
Billing
| Command | Description |
|---|
wassist upgrade | Upgrade your subscription plan. |
Configuration
The CLI stores its auth token and active number locally via conf. The default backend is https://backend.wassist.app; this can be overridden in the config file for development.
Policies
By sending messages through the Wassist CLI you agree to:
Violations may restrict your WhatsApp Business Account or Wassist account. 