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 token to your OS credential store.

Start A Sandbox Session

Pin the session to the phone you'll send test messages from.

hookmyapp sandbox start --phone +15551234567

The sandbox is a shared test WhatsApp number across all sandbox users. It removes Meta paperwork: no Business Manager, no verified phone, no access token of your own. The cost is that message content sent to it is not private.

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 a signature-verifying receiver at POST /webhook, a sendMessage(to, text) helper, 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

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

Send A Test Message

WhatsApp the shared 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 Sandbox To Production

The receiver code does not change. Only three env values do:

  • WHATSAPP_API_URL flips from the sandbox proxy URL to https://graph.facebook.com/v24.0.
  • WHATSAPP_ACCESS_TOKEN flips from the sandbox session activation code to your WABA's long-lived access token.
  • WHATSAPP_PHONE_NUMBER_ID flips from the shared sandbox number's ID to your WABA's phone number ID.

hookmyapp env <waba-id> --write .env writes the production values once you connect a WABA.

Next Steps