CLI

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

wassist login

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:

wassist whoami

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

The 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

Supported types: JPEG, PNG, MP4, 3GPP, AAC, MP4 audio, MPEG, AMR, OGG, PDF, DOCX, XLSX, PPTX.

wassist messages send "Choose one" \
  --reply "Yes|confirm" \
  --reply "No|deny"

Max 3 quick replies. The pipe separates label from the value sent back when tapped.

wassist messages send "Visit us" \
  --url-button "Shop Now|https://shop.com"

Max 1 URL button. URL and quick-reply buttons cannot be mixed in the same message.

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?

In interactive mode you can reply inline. The > 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

wassist upgrade

A Wassist subscription is required to connect your own number.

Link your WhatsApp Business Account

wassist numbers add

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

To switch back to the sandbox: 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:

WhatsApp Business Policy — opt-in, prohibited content, frequency, and platform rules.
Meta AI Provider pricing policy — per-message pricing for AI-driven non-template messages in certain markets.

Violations may restrict your WhatsApp Business Account or Wassist account.

Introduction

Advanced

Install

Authenticate

Sending messages

Validation rules

Outside the 24-hour window

Streaming inbound messages

Combining the CLI with webhooks

Moving to your own number

Command reference

Authentication

Number management

Messaging

Billing

Configuration

Policies

​Install

​Authenticate

​Sending messages

​Validation rules

​Outside the 24-hour window

​Streaming inbound messages

​Combining the CLI with webhooks

​Moving to your own number

​Command reference

​Authentication

​Number management

​Messaging

​Billing

​Configuration

​Policies

Install

Authenticate

Sending messages

Validation rules

Outside the 24-hour window

Streaming inbound messages

Combining the CLI with webhooks

Moving to your own number

Command reference

Authentication

Number management

Messaging

Billing

Configuration

Policies