CLI

Manage WhatsApp numbers, messages, templates, and webhooks from the terminal

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.

Using an MCP-capable agent? Use Project MCP when the agent should manage Kapso without shell access.

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 "[phone]"
kapso whatsapp numbers get --phone-number-id <meta-id>

# Start WhatsApp number setup
kapso whatsapp numbers new

# Health check
kapso whatsapp numbers health "[phone]"

# Resolve a number reference to its canonical ID
kapso whatsapp numbers resolve "[phone]"

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 "[phone]" \
  --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 "[phone]"

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

Calls

Read-only. Requires CLI 0.19.1 or later.

# List calls (one page; filter by direction, status, since, until)
kapso whatsapp calls list --phone-number-id <id> --limit 20

# Look up a call by its Meta call ID; the result's id is Kapso's call UUID
kapso whatsapp calls get <wacid> --phone-number-id <id>

# Inspect a native recording or transcript by Kapso call UUID
kapso whatsapp calls artifact <call-uuid> --kind transcription

# Download the original file
kapso whatsapp calls artifact <call-uuid> --kind recording --download --out call.ogg

calls artifact needs KAPSO_API_KEY. Recording inspection prints metadata only. Transcript inspection adds a short text preview; use --download for Meta’s original JSON. Existing files aren’t replaced unless you pass --force. See Recordings and transcripts.

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, whatsapp.contact.identity_changed.

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"

Local workflow development

Use these commands when you want to keep Kapso workflows and functions in a local repository.

# Create a local workspace
mkdir kapso-workflows
cd kapso-workflows
npm init -y

# Optional: install the workflow code library
npm install --save-dev @kapso/workflows

# Link this directory to one Kapso project
kapso login
kapso link --project <project-id>
kapso pull

kapso pull writes local source files for workflows and functions. If you edit workflows with @kapso/workflows, build the generated JSON before pushing:

kapso build
kapso push --dry-run
kapso push workflow <workflow-slug>

You can also push one function or everything in the repo:

kapso push function <function-slug>
kapso push

If a pull is blocked by local edits, inspect or replace the incoming changes:

kapso pull --diff
kapso pull --overwrite

See Build locally for the full workflow source-control guide.

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