CLI

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 "+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, 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

Getting started

WhatsApp

For your team

Onboard customers

Automations

Installation

Authentication

Project context

Setup

Numbers

Messages

Send a text message

Send with a JSON payload

List and get messages

Conversations

Templates

Webhooks

Create a webhook

Manage webhooks

Message buffering

Customers

Local workflow development

Output formats

Help

​Installation

​Authentication

​Project context

​Setup

​Numbers

​Messages

​Send a text message

​Send with a JSON payload

​List and get messages

​Conversations

​Templates

​Webhooks

​Create a webhook

​Manage webhooks

​Message buffering

​Customers

​Local workflow development

​Output formats

​Help

Installation

Authentication

Project context

Setup

Numbers

Messages

Send a text message

Send with a JSON payload

List and get messages

Conversations

Templates

Webhooks

Create a webhook

Manage webhooks

Message buffering

Customers

Local workflow development

Output formats

Help