WhatsApp quickstart

Two minutes from npm install to a webhook receiving real WhatsApp messages on your laptop.

What you'll have

In a few minutes you'll be sending and receiving real WhatsApp messages from your own app, running on your laptop. WhatsApp a test number from your phone, watch the message land in your code in under a second, and reply right back.

Install and authenticate

npm install -g @gethookmyapp/cli
hookmyapp login

hookmyapp login opens a browser tab. After sign-in, the CLI writes a credential token to a local file in your config directory.

Start a sandbox session

hookmyapp sandbox start

The CLI prints an 8-char bind code and a QR. WhatsApp that code to the sandbox number from the phone you want to bind. That message is what pins the session to your phone (it proves you own the number; we can't take your word for it). Open the QR's wa.me link on the same phone to auto-fill the message.

The sandbox is a test WhatsApp number you can use right away. It removes Meta paperwork: no Business Manager, no verified phone, no access token of your own.

Clone and run the starter kit

git clone https://github.com/hookmyapp/webhook-starter-kit.git
cd webhook-starter-kit
npm install
hookmyapp sandbox env --write .env
npm start

The starter kit ships signature-verifying receivers at POST /webhook/whatsapp and POST /webhook/instagram (it serves both channels at once), per-channel send(to, text) helpers, an auto-reply you can customize, and an .env.example the CLI fills in. hookmyapp sandbox env --write .env writes the sandbox proxy URL, your session activation code, the test number's phone ID, and a VERIFY_TOKEN for HMAC verification.

Open the tunnel

hookmyapp sandbox listen --path /webhook/whatsapp

This opens a secure tunnel from a HookMyApp-managed public hostname to http://localhost:3000/webhook/whatsapp. The tunnel lives as long as the CLI process runs.

Send a test message

WhatsApp the test number from your pinned phone. Your receiver logs the inbound webhook. The starter kit's auto-reply lands back on your phone.

You can also send a one-shot test from the CLI:

hookmyapp sandbox send --message "hello from my app"

From the sandbox to your own number

When you're ready for your own WhatsApp number, the dev loop stays the same: same receiver code, same local tunnel, just a real channel.

Connect your WhatsApp number

hookmyapp channels connect

Opens Meta embedded signup in a browser tab. Pick a Business Manager, create or select a WhatsApp Business Account, verify a phone number. The CLI lands you back with a new Channel ID (ch_xxxxxxxx). Confirm with:

hookmyapp channels list

You can connect a brand-new number or one you already use in the WhatsApp Business app. See Connect WhatsApp for both paths.

Pull your number's env

hookmyapp channels env ch_xxxxxxxx --write .env

Overwrites the sandbox values in .env with your own number's. Your own number reports its base URL as META_GRAPH_API_URL (https://graph.facebook.com/v24.0) instead of the sandbox's WHATSAPP_API_URL, plus your long-lived WHATSAPP_ACCESS_TOKEN, your WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_WABA_ID, and HOOKMYAPP_CHANNEL_ID. The receiver code does not change; point your sender at whichever base-URL variable is set.

Listen locally against your number

hookmyapp channels listen ch_xxxxxxxx --path /webhook/whatsapp

Same shape as hookmyapp sandbox listen, but on your own channel. Opens a secure tunnel from a HookMyApp-managed hostname to localhost:3000/webhook/whatsapp and points Meta at it while the CLI runs. Stop the CLI (Ctrl-C) and the tunnel is reclaimed; Meta's webhook URL reverts to whatever was set before.

Real WhatsApp messages to your verified number now arrive on your laptop. The same auto-reply works.

Set your own webhook URL (when you deploy)

When your receiver is deployed behind a stable public URL, replace the tunnel with that URL:

hookmyapp channels webhook set ch_xxxxxxxx \
  --url https://api.yourapp.com/webhook/whatsapp \
  --verify-token $(openssl rand -hex 32)

HookMyApp writes it to Meta's override_callback_uri via the Graph API.

Next steps