Skip to main content
The Kapso CLI gives you full control over your WhatsApp integration from the command line. Send messages, manage webhooks, inspect conversations, and automate workflows — all without leaving your terminal.

​
Installation

npm install -g @kapso/cli
Requires Node.js >= 20.19.

​
Authentication

Browser login (interactive) 
kapso login
Opens your browser to authenticate. Your session is stored locally in ~/.kapso/cli/. API key (CI / non-interactive environments) 
export KAPSO_API_KEY=your_project_api_key
When set, all project-scoped commands use the API key directly — no browser needed. Use this for CI pipelines, Docker containers, scripts, or any headless environment. You can create your project API key in the Kapso dashboard.

​
Project context

After login, the CLI remembers your active project. Switch between projects with: 
kapso projects list
kapso projects use <project-id>
kapso projects current
Check your full setup status: 
kapso status

​
Setup

Connect a WhatsApp number to your project: 
kapso setup
This resolves your project and customer, then generates a setup link to connect or provision a WhatsApp number. For automation: 
kapso setup \
  --customer <customer-id> \
  --country US \
  --connection-type dedicated

​
Numbers

# List all numbers
kapso whatsapp numbers list

# Get a specific number
kapso whatsapp numbers get "+1234567890"
kapso whatsapp numbers get --phone-number-id <meta-id>

# Start WhatsApp number setup
kapso whatsapp numbers new

# Health check
kapso whatsapp numbers health "+1234567890"

# Resolve a number reference to its canonical ID
kapso whatsapp numbers resolve "+1234567890"
Most WhatsApp commands accept --phone-number or --phone-number-id to specify which number to act on. You can also pass the number as a positional argument where supported.

​
Messages

​
Send a text message

kapso whatsapp messages send \
  --phone-number-id <id> \
  --to "+1234567890" \
  --text "Hello from Kapso CLI"

​
Send with a JSON payload

For media, interactive, or any advanced message type, pass a JSON payload: 
# From a file
kapso whatsapp messages send --phone-number-id <id> --input message.json

# From stdin
cat message.json | kapso whatsapp messages send --phone-number-id <id> --stdin

​
List and get messages

# List messages for a number
kapso whatsapp messages list --phone-number-id <id>

# Filter by direction, status, or time range
kapso whatsapp messages list \
  --phone-number-id <id> \
  --direction inbound \
  --since "2025-01-01T00:00:00Z" \
  --limit 50

# Get a specific message
kapso whatsapp messages get <message-id>

​
Conversations

# List conversations (most recent first)
kapso whatsapp conversations list --phone-number-id <id>

# Filter by status or contact phone
kapso whatsapp conversations list --phone-number-id <id> --status active --phone "+1234567890"

# Get a specific conversation
kapso whatsapp conversations get <conversation-id>

​
Templates

# List templates for a number
kapso whatsapp templates list --phone-number-id <id>

# Filter by status or category
kapso whatsapp templates list --phone-number-id <id> --status APPROVED --category UTILITY

# Get a specific template
kapso whatsapp templates get <template-id> --phone-number-id <id>

# Create a template from JSON
kapso whatsapp templates new --phone-number-id <id> --input template.json

​
Webhooks

​
Create a webhook

kapso whatsapp webhooks new \
  --phone-number-id <id> \
  --url "https://example.com/webhook" \
  --event whatsapp.message.received \
  --event whatsapp.message.delivered \
  --active
Available events: whatsapp.message.received, whatsapp.message.sent, whatsapp.message.delivered, whatsapp.message.read, whatsapp.message.failed, whatsapp.conversation.created, whatsapp.conversation.ended, whatsapp.conversation.inactive.

​
Manage webhooks

# List webhooks
kapso whatsapp webhooks list --phone-number-id <id>

# Update a webhook
kapso whatsapp webhooks update <webhook-id> --phone-number-id <id> --inactive

# Delete a webhook
kapso whatsapp webhooks delete <webhook-id> --phone-number-id <id>

​
Message buffering

Buffer multiple whatsapp.message.received events into a single delivery: 
kapso whatsapp webhooks new \
  --phone-number-id <id> \
  --url "https://example.com/webhook" \
  --event whatsapp.message.received \
  --buffer-enabled \
  --buffer-window-seconds 5 \
  --max-buffer-size 10 \
  --active

​
Customers

# List customers
kapso customers list

# Get a customer
kapso customers get <customer-id>

# Create a customer
kapso customers new --name "Acme Corp" --external-id "acme-123"

​
Output formats

All commands support --output json or --output human. Most default to json — pipe into jq for scripting: 
kapso whatsapp numbers list --output json | jq '.[0].id'

​
Help

# General help
kapso help

# Help for a specific command
kapso help whatsapp messages send