Connecting Real WhatsApp

Meta gives every new app a test number that can message up to five recipients. That is enough to develop against the real API. Your machine needs to be reachable from the internet, which is what ngrok is for.

Create the Meta app

1. Make a developer account and a business app

   Sign up at developers.facebook.com and create an app of type Business. On the dashboard, press Set up under the WhatsApp box to attach the WhatsApp and Webhooks products.

2. Copy the app credentials

   From App settings, Basic:

   META_APP_ID=your_app_id
   META_APP_SECRET=your_app_secret
   META_API_VERSION=v22.0

   The app secret is what verifies that incoming webhooks really came from Meta.

3. Copy the number and generate a token

   From WhatsApp, API Setup, select the test number and copy its phone number ID. Press Generate access token for a 24 hour token.

   WHATSAPP_CLOUD_NUMBER_ID=your_phone_number_id
   WHATSAPP_API_TOKEN=your_access_token

   A 24 hour token is fine for an afternoon. For anything longer, create a system user token instead.

4. Add your phone as a recipient

   Still on the API Setup page, add your own number, then send yourself the test template message. You must reply to that message from your phone. Until you do, Meta only lets the app send templates, not ordinary replies.

Expose your local server

Meta needs a public HTTPS URL. Create a free static domain in the ngrok dashboard under Domains, then:

ngrok config add-authtoken YOUR_AUTHTOKEN
ngrok http 8000 --domain your-domain.ngrok-free.app

Leave that running. Port 8000 is what the API container publishes.

Point Meta at your tunnel

1. Invent a verify token

   Any string will do. It is a shared secret used once, during the handshake.

   WHATSAPP_VERIFY_TOKEN=some_random_string
   MOCK_WHATSAPP=False

   Restart the API so it picks up the changes.

2. Fill in the webhook

   In the Meta dashboard go to WhatsApp, Configuration, Webhook and set:

   Field	Value
   Callback URL	https://your-domain.ngrok-free.app/webhooks
   Verify token	Exactly your WHATSAPP_VERIFY_TOKEN

   The /webhooks suffix is easy to forget and is required.

3. Verify and subscribe

   Press Verify and save. Meta sends a GET request with a challenge, and you should see it in both the ngrok and API logs. Then scroll down to Webhook Fields and subscribe to messages. Without that subscription, verification succeeds and no messages ever arrive.

Message the test number from your phone. You should get a reply.

Reading the failures