> ## Documentation Index > Fetch the complete documentation index at: https://docs.hookmyapp.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI > Manage WhatsApp channels, messages, templates, media, profile, webhooks, and sandboxes from the terminal. ## Install ```bash theme={null} npm install -g @gethookmyapp/cli ``` Requires Node.js 20 or newer. ## Authenticate ```bash theme={null} hookmyapp login hookmyapp logout ``` For terminal-only sessions, use `hookmyapp login --email `. ## Workspaces A workspace is the tenancy boundary for every other command.
Pick one before you connect channels. ```bash theme={null} # 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: ```bash theme={null} # 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`). ```bash theme={null} # 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: ```bash theme={null} # 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 ```bash theme={null} # 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. ```bash theme={null} # 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`: ```json theme={null} { "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. ```bash theme={null} # 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: ```text theme={null} id=media_123 ``` `media get` returns Meta media metadata, including the short-lived download URL. `media download --out -` streams bytes to stdout: ```bash theme={null} hookmyapp whatsapp media download media_123 --channel 15551234567 --out - > image.jpg ``` ### Business profile Read or update the WhatsApp Business profile customers see in WhatsApp. ```bash theme={null} # 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`: ```json theme={null} { "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: ```bash theme={null} # Listen for messages on your laptop hookmyapp channels listen 15551234567 ``` For a deployed receiver, point Meta at your own public URL: ```bash theme={null} # 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: ```bash theme={null} # 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](/whatsapp/sandbox) for the full flow. ```bash theme={null} # 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: ```bash theme={null} # 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. ```bash theme={null} # 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 `. 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. ```bash theme={null} # 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 ```bash theme={null} # Show subscription status hookmyapp billing status # Open Billing page hookmyapp billing manage # Upgrade plan hookmyapp billing upgrade ``` ## Config Persistent CLI settings. ```bash theme={null} # 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}}`. ```bash theme={null} hookmyapp channels list --json | jq '.[0].id' ``` Other global flags: `--workspace ` overrides the active workspace for one command, and `--debug` logs the HTTP requests the CLI makes. ## Help ```bash theme={null} # Full command surface hookmyapp --help # Flags and options for any command hookmyapp channels webhook set --help ``` ## Next steps * [Sandbox](/whatsapp/sandbox): Start a sandbox session and pull env values. * [Connect WhatsApp](/whatsapp/connect-waba): Connect your own WhatsApp number via embedded signup.