Sandbox

A shared test number for local development. No Meta paperwork. Run hookmyapp sandbox env --write .env and start building.

What The Sandbox Is

One shared test WhatsApp number across all sandbox users. You pin a session to your own phone number. You receive messages sent to the test number from your pinned phone. You send replies only back to your pinned phone.

This removes the Meta paperwork: you don't need a Facebook Business Manager, a verified phone, or an access token. You do pay the cost that the number is shared, so message content sent to it is not private.

Start A Session

Pin your session to the phone number that will send test messages.

hookmyapp sandbox start --phone +15551234567
hookmyapp sandbox status

Pull Env Values

Write the sandbox env values to a .env file your server can load.

hookmyapp sandbox env --write .env
  • VERIFY_TOKEN: the HMAC secret your server uses to verify X-HookMyApp-Signature-256 on incoming webhooks.
  • PORT: where your local server listens. Defaults to 3000.
  • WHATSAPP_API_URL: the sandbox proxy URL your app POSTs messages to.
  • WHATSAPP_ACCESS_TOKEN: the session activation code, used as the Bearer token.
  • WHATSAPP_PHONE_NUMBER_ID: the ID of the shared test number.

Session Lifecycle

  • Activate: hookmyapp sandbox start --phone +<E.164> pins a session to your phone.
  • Expiry: sessions expire after 24 hours idle.
  • Reactivate: run hookmyapp sandbox start --phone +<E.164> again with the same phone. You get a fresh activation code and new env values.
  • Stop early: hookmyapp sandbox stop tears down the session immediately.

Local Tunneling

To stream inbound webhooks to localhost, open a Cloudflare tunnel with hookmyapp sandbox listen. The tunnel connects a HookMyApp-managed public hostname to http://localhost:3000/webhook by default. The tunnel lives as long as the CLI process runs.

The public hostname differs by environment:

  • Staging: staging-sandbox.hookmyapp.com. Note the hyphen order: staging-sandbox, not sandbox-staging.
  • Production: sandbox.hookmyapp.com.
  • The CLI picks the right URL automatically based on which account you logged into. You don't configure it.
hookmyapp sandbox listen
# In another shell:
hookmyapp sandbox send --message "hello from my phone"

Send A Test Message

The sandbox only sends to your pinned phone. There is no --to flag on sandbox send; the sandbox proxy rejects other recipients.

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

Next Steps

  • Quickstart: Pair the sandbox with the reference receiver in two minutes.
  • Webhook Routing: See how sandbox and production URLs differ.