wati-cli

Agent-friendly CLI for the WATI WhatsApp Business API. Every command returns structured JSON to stdout, errors go to stderr, and exit codes are meaningful — built to be consumed by AI agents, scripts, and automation pipelines.

Install

npm install -g wati-cli
# or run directly
npx wati configure init

Requires Node.js ≥ 18.

Quick Start

# 1. Configure credentials (interactive)
wati configure init

# 2. List your contacts
wati contacts list --page-size 10

# 3. Send a message
wati conversations send-text --target +5511999887766 --text "Hello from the CLI"

Authentication

Credentials are resolved in order:

1. CLI flags: --base-url, --token, --tenant-id
2. Environment variables: WATI_BASE_URL, WATI_AUTH_TOKEN, WATI_TENANT_ID
3. Config file: ~/.watirc (created by wati configure init, mode 0600)

Global Options

| Flag | Description | |---|---| | --base-url <url> | WATI API base URL | | --token <token> | Bearer auth token | | --tenant-id <id> | Tenant ID (multi-channel setups) | | --pretty | Pretty-print JSON output | | --quiet | Suppress output (exit code only) |

Commands

contacts

wati contacts list --page-number 1 --page-size 20
wati contacts get <target>                          # by phone, ID, or Channel:Phone
wati contacts add --number +5511... --name "Jane"
wati contacts update --data '[{"target":"+55...","customParams":[{"name":"k","value":"v"}]}]'
wati contacts count [--date-from <date>] [--date-to <date>]
wati contacts assign-teams --target +55... --teams "Sales,VIP"

conversations

wati conversations messages <target> --page-size 10
wati conversations send-text --target +55... --text "Your order shipped"
wati conversations send-file --target +55... --file ./invoice.pdf [--caption "Invoice"]
wati conversations send-file-url --target +55... --url https://example.com/file.pdf
wati conversations download-media <messageId> --output ./photo.jpg
wati conversations send-interactive --target +55... --type buttons --data '{"body":"Pick one","buttons":[{"text":"Yes"},{"text":"No"}]}'
wati conversations assign-operator --target +55... --email [email protected]
wati conversations update-status --target +55... --status solved

templates

wati templates list --page-size 50 [--channel <channel>]
wati templates get <templateId>
wati templates send --template-name order_confirm --broadcast-name "Jan batch" --recipients '[{"phone_number":"+55..."}]'
wati templates schedule --template-name promo --broadcast-name "Feb sale" --scheduled-at 2026-03-01T09:00:00Z --recipients '[...]'

campaigns

wati campaigns list --page-size 20 [--channel <channel>]
wati campaigns get <broadcastId>
wati campaigns recipients <broadcastId> --page-size 100
wati campaigns overview --date-from 2026-01-01T00:00:00Z --date-to 2026-02-01T00:00:00Z

channels & chatbots

wati channels list
wati chatbots list
wati chatbots start --chatbot-id bot_123 --target +55...

webhooks

wati webhooks list
wati webhooks subscribe --url https://my-server.com/hook --events message,sessionMessageSent
wati webhooks update <id> --url https://new-url.com/hook
wati webhooks update <id> --events message,sentMessageREAD,templateMessageSent
wati webhooks update <id> --status Disabled
wati webhooks delete <id>

Supported event types: message, newContactMessageReceived, sessionMessageSent, templateMessageSent, sentMessageDELIVERED, sentMessageREAD, sentMessageREPLIED, whatsAppPaymentCaptured, ctaUrlClicked

configure

wati configure init    # interactive credential setup
wati configure show    # display config (token masked)
wati configure path    # print config file location

Output Format

All commands write JSON to stdout. Errors write JSON to stderr.

# Success → stdout, exit 0
wati contacts count
{"contact_count":1842}

# API error → stderr, exit 2
wati contacts get invalid
{"error":"Contact not found","status":404}

# Client error → stderr, exit 1
wati contacts list
{"error":"Missing auth token"}

Use --pretty for human-readable output:

wati contacts list --page-size 2 --pretty

Testing

Run the integration test harness against the live API:

npm run test:api

This exercises every command group (contacts, conversations, templates, campaigns, channels, chatbots, webhooks) and produces a summary report. Credentials are read from ~/.watirc — nothing sensitive is stored in the repo.

Agent Integration

This CLI is designed for agentic consumption. Every command is deterministic, returns structured JSON, and uses meaningful exit codes — no interactive prompts in non-TTY mode.

Example agent workflow:

# Check if contact exists
wati contacts get +5511999887766

# If not found (exit 2, status 404), create them
wati contacts add --number +5511999887766 --name "New Customer"

# Send a template message
wati templates send \
  --template-name order_confirmation \
  --broadcast-name "auto-$(date +%s)" \
  --recipients '[{"phone_number":"+5511999887766","custom_params":[{"name":"order_id","value":"ORD-9921"}]}]'

# Mark conversation handled
wati conversations update-status --target +5511999887766 --status solved

License

MIT