CLI

Install

npm install -g @gethookmyapp/cli

Requires Node.js 20 or newer.

Authenticate

hookmyapp login
hookmyapp logout

For terminal-only sessions, use hookmyapp login --email <you@example.com>.

Workspaces

A workspace is the tenancy boundary for every other command.
Pick one before you connect channels.

# List workspaces
hookmyapp workspace list

# Switch active workspace
hookmyapp workspace use acme

# Create workspace
hookmyapp workspace new "Acme Inc"

# Show active workspace
hookmyapp workspace current

# Rename active workspace
hookmyapp workspace rename "Acme Corp"

Manage who has access:

# List workspace members
hookmyapp workspace members list

# Invite a teammate
hookmyapp workspace members invite teammate@acme.com

# Change teammate role
hookmyapp workspace members role teammate@acme.com --role admin

# Remove a teammate
hookmyapp workspace members remove teammate@acme.com

# Cancel an invite
hookmyapp workspace invites cancel teammate@acme.com

Channels

Connect your own WhatsApp number, then run per-channel operations.
Address a channel by its ID (ch_xxxxxxxx from channels list) or its phone number (15551234567).

# Connect WhatsApp number
hookmyapp channels connect whatsapp

# List connected channels
hookmyapp channels list

# Show channel details
hookmyapp channels show 15551234567

# Enable forwarding
hookmyapp channels enable 15551234567

# Disable forwarding
hookmyapp channels disable 15551234567

# Disconnect channel
hookmyapp channels disconnect 15551234567

Pull the values your server needs, or check channel health:

# Write channel env values
hookmyapp channels env 15551234567 --write .env

# Print channel token
hookmyapp channels token 15551234567

# Health check: Meta connection, forwarding, quality rating, recent failures
hookmyapp channels health 15551234567

WhatsApp commands

Use the phone number anywhere a command asks for a WhatsApp channel.

Messages

# Send text message
hookmyapp whatsapp messages send --channel 15551234567 --to +14441234567 --text "hi"

# Mark message as read
hookmyapp whatsapp messages read wamid.ABC --channel 15551234567

Templates

Manage templates on the WABA behind the channel. Templates must be approved by Meta before you can send them.

# List templates
hookmyapp whatsapp templates list --channel 15551234567

# List only approved marketing templates as JSON
hookmyapp whatsapp templates list --channel 15551234567 \
  --status APPROVED \
  --category MARKETING \
  --json

# Get template
hookmyapp whatsapp templates get hello_world --channel 15551234567

# Create template from JSON
hookmyapp whatsapp templates create --channel 15551234567 --body @template.json

# Delete template
hookmyapp whatsapp templates delete hello_world --channel 15551234567

Example template.json:

{
  "name": "order_update",
  "category": "UTILITY",
  "language": "en_US",
  "components": [
    {
      "type": "BODY",
      "text": "Hi {{1}}, your order {{2}} has shipped."
    }
  ]
}

Create returns Template created. in human mode. Use --json when you need Meta’s raw create response in a script.

Media

Upload media first, then use the returned media ID in message payloads. HookMyApp passes the media through to Meta. It does not store the file.

# Upload media
hookmyapp whatsapp media upload --channel 15551234567 --file ./image.jpg

# Upload with an explicit MIME type
hookmyapp whatsapp media upload --channel 15551234567 \
  --file ./invoice.pdf \
  --type application/pdf

# Get media metadata
hookmyapp whatsapp media get media_123 --channel 15551234567

# Download media
hookmyapp whatsapp media download media_123 --channel 15551234567 --out ./image.jpg

# Delete media
hookmyapp whatsapp media delete media_123 --channel 15551234567

Typical upload output:

id=media_123

media get returns Meta media metadata, including the short-lived download URL. media download --out - streams bytes to stdout:

hookmyapp whatsapp media download media_123 --channel 15551234567 --out - > image.jpg

Business profile

Read or update the WhatsApp Business profile customers see in WhatsApp.

# Get business profile
hookmyapp whatsapp profile get --channel 15551234567

# Get only selected fields
hookmyapp whatsapp profile get --channel 15551234567 --fields about,email,websites

# Update business profile
hookmyapp whatsapp profile update --channel 15551234567 \
  --about "Fast support from Acme" \
  --description "Order updates and customer support" \
  --email support@example.com \
  --website https://example.com

# Or send the complete Meta profile body
hookmyapp whatsapp profile update --channel 15551234567 --body @profile.json

Example profile.json:

{
  "messaging_product": "whatsapp",
  "about": "Fast support from Acme",
  "description": "Order updates and customer support",
  "email": "support@example.com",
  "vertical": "ECOMMERCE",
  "websites": ["https://example.com"]
}

WhatsApp allows at most two website URLs. Updates return Profile updated. in human mode. Use --json for the raw Meta response.

Receive webhooks

There are two ways to tell HookMyApp where to send inbound messages for your own number. For local development, send messages to your laptop while the CLI runs:

# Listen for messages on your laptop
hookmyapp channels listen 15551234567

For a deployed receiver, point Meta at your own public URL:

# Set deployed webhook URL
hookmyapp channels webhook set 15551234567 \
  --url https://api.acme.com/whatsapp/webhook \
  --verify-token $(openssl rand -hex 32)

# Show webhook URL
hookmyapp channels webhook show 15551234567

# Clear webhook URL
hookmyapp channels webhook clear 15551234567

# Show the HMAC signing secret (used to verify X-HookMyApp-Signature-256)
hookmyapp channels webhook hmac show 15551234567

Use one message destination per channel: either channels listen for local testing or a deployed webhook URL. Read the delivery history. Copy the delivery ID (wd_...) from the list output to open one delivery:

# List delivery history
hookmyapp channels logs list 15551234567

# Show delivery details
hookmyapp channels logs show wd_xxxxxxxx

Sandbox

Test on WhatsApp with no Meta setup.
See Sandbox for the full flow.

# Start a sandbox session
hookmyapp sandbox start

# List sandbox sessions
hookmyapp sandbox status

# Write sandbox env values
hookmyapp sandbox env 15551234567 --write .env

# Listen for sandbox messages
hookmyapp sandbox listen 15551234567

# Send sandbox test message
hookmyapp sandbox send 15551234567 --message "hello from my app"

# List sandbox deliveries
hookmyapp sandbox logs 15551234567

# Stop sandbox session
hookmyapp sandbox stop 15551234567

The sandbox webhook URL works like a channel webhook URL:

# Show sandbox webhook URL
hookmyapp sandbox webhook show 15551234567

# Set sandbox webhook URL
hookmyapp sandbox webhook set 15551234567 --url https://example.com/webhook

# Clear sandbox webhook URL
hookmyapp sandbox webhook clear 15551234567

Alerts

Your own alert phone: where we reach you if something stops working.

# See your alert phone and what it receives
hookmyapp alerts phone status

# Add or change it (international format)
hookmyapp alerts phone set +14155552671

# Get the code by SMS instead of WhatsApp
hookmyapp alerts phone set +14155552671 --sms

# Finish verification with the code we sent
hookmyapp alerts phone verify 123456

# Remove your alert phone
hookmyapp alerts phone remove

We send a 6-digit code to confirm the number, and set asks for it. In a script there is no prompt: run set with --json, then finish with alerts phone verify <code>. Alerts are on once the number is verified.

Notifications

Notifications from HookMyApp delivered straight to your AI agent, like Claude Code, ChatGPT, or Codex: failing webhooks, disconnected channels, usage limits, and product announcements.

# List open notifications, newest first
hookmyapp notifications

# Include ones already acknowledged
hookmyapp notifications list --all

# Mark a notification seen after relaying it to a human
hookmyapp notifications ack ntf_A1b2C3d4

Acknowledging records that the notification was read. It does not mean the problem is fixed.

Billing

# Show subscription status
hookmyapp billing status

# Open Billing page
hookmyapp billing manage

# Upgrade plan
hookmyapp billing upgrade

Config

Persistent CLI settings.

# Show CLI settings
hookmyapp config show

# Turn telemetry off
hookmyapp config set telemetry off

# Turn telemetry on
hookmyapp config set telemetry on

Output formats

Most commands take --json for machine-clean output (notifications go to stderr) and --human to force human formatting when stdout is not a TTY.
In --json mode, errors use the envelope {"error":{"code":"...","message":"...","status":NNN}}.

hookmyapp channels list --json | jq '.[0].id'

Other global flags: --workspace <slug> overrides the active workspace for one command, and --debug logs the HTTP requests the CLI makes.

Help

# Full command surface
hookmyapp --help

# Flags and options for any command
hookmyapp channels webhook set --help

Next steps

Sandbox: Start a sandbox session and pull env values.
Connect WhatsApp: Connect your own WhatsApp number via embedded signup.

Getting started

Sending & receiving

Tools

Self-managed setup

FAQs

API Reference

Install

Authenticate

Workspaces

Channels

WhatsApp commands

Messages

Templates

Media

Business profile

Receive webhooks

Sandbox

Alerts

Notifications

Billing

Config

Output formats

Help

Next steps

​Install

​Authenticate

​Workspaces

​Channels

​WhatsApp commands

​Messages

​Templates

​Media

​Business profile

​Receive webhooks

​Sandbox

​Alerts

​Notifications

​Billing

​Config

​Output formats

​Help

​Next steps

Install

Authenticate

Workspaces

Channels

WhatsApp commands

Messages

Templates

Media

Business profile

Receive webhooks

Sandbox

Alerts

Notifications

Billing

Config

Output formats

Help

Next steps