WhatsApp Bot — Live Testing Guide

Option A — cloudflared Terminal (recommended — free, no signup)

# install once
brew install cloudflared

# start the tunnel (leave this running in its own terminal tab)
cloudflared tunnel --url http://localhost:8001

It prints a line like:

+--------------------------------------------------------+
|  https://random-words-1234.trycloudflare.com           |
+--------------------------------------------------------+

That HTTPS address is your public base URL. Your webhook callback URL will be that + /api/v1/whatsapp/webhook/ — keep it handy for Step 6.

Option B — ngrok

brew install ngrok          # or download from ngrok.com
ngrok config add-authtoken <your-token>   # free account required now
ngrok http 8001

Use the https://…ngrok-free.app URL it shows.

1. Go to developers.facebook.com and log in. If it's your first time, complete "Register as a Meta Developer" (you'll verify via phone/email and accept the terms).
2. Top‑right → My Apps → Create App.
3. For use case, pick "Other" → app type "Business" → give it a name (e.g. OrderPin Bot) and continue.
4. On the new app's dashboard, find WhatsApp in the product list and click "Set up". This creates a free test WhatsApp Business Account and a test phone number for you automatically.

Add your phone to the recipient allow‑list

Test numbers can only message numbers you explicitly allow. On the API Setup page, in the "To" field, click "Manage phone number list" → add your personal WhatsApp number (with country code) → confirm the code WhatsApp sends you. You can add up to 5.

1. In the admin portal go to Settings → Notifications → Channels. (Shortcut: the WhatsApp Automation page has a "Connect number" button that jumps here.)
2. Add a channel of type WhatsApp, provider Meta Business API (meta_wa). Fill in:

3. Enable the channel (the Enabled toggle). 🔑 This is what flips the bot from console mode to live — it's the single switch that makes the bot actually send messages through Meta.
4. Save.

The seeded demo outlets use fake numbers (9876500001…), so the bot won't know your real phone yet. Fix it in one of two ways:

• In the UI: Masters → Outlets → edit any outlet → set its phone to your real WhatsApp number (the 10‑digit number, e.g. 98765 43210) → save.
• Or via shell Terminal — replace the number with yours:

  # from orderpin-backend/
  ./venv/bin/python manage.py shell -c "
  from apps.masters.models import Outlet
  o = Outlet.objects.exclude(phone='').first()
  o.phone = '9876543210'   # ← your real WhatsApp number, 10 digits
  o.save()
  print('Bot will now recognise', o.phone, 'as', o.name)
  "

The match is forgiving about the country code: if you message from +91 98765 43210, it matches an outlet stored as 9876543210.

1. App dashboard → WhatsApp → Configuration → in the Webhook section click Edit.
2. Callback URL: your tunnel URL + the webhook path:

   https://random-words-1234.trycloudflare.com/api/v1/whatsapp/webhook/

3. Verify token: the exact same random string from Step 3/4.
4. Click Verify and Save. Meta immediately sends a GET with a challenge; OrderPin's webhook checks your verify token and echoes it back. ✅ Success = the dialog closes without error.
5. Back on the Configuration page, under Webhook fields, click Manage and Subscribe to the messages field. This is mandatory — without it, no inbound messages are delivered.

1. Open WhatsApp on your phone and start a chat with the test number shown on Meta's API Setup page (save it to contacts first, or tap the link Meta provides).
2. Send hi.
3. You should receive, in order:
   • 👋 "Hi <your outlet name>! Let's build your order."
   • A tappable product list (Browse Catalog)
   • A prompt: "How many units…?" → reply with a number
   • An Add another / Checkout menu → tap Checkout
   • 🎉 "Order ORDxxxx placed! Total ₹…"
4. Back in OrderPin, open Orders — your new order is there. Open WhatsApp → Conversations to see the full transcript.

Watch it live

Keep an eye on the backend terminal (the one running runserver 8001) while you test — every inbound delivery shows as a POST /api/v1/whatsapp/webhook/ 200 line, and console‑mode replies print there too.

• Permanent access token — replace the 24h token with a System User token (Business Settings → Users → System Users → Add → assign the app → Generate token with whatsapp_business_messaging + whatsapp_business_management). It doesn't expire.
• Your own business number — add and verify a real phone number in WhatsApp Manager (it can't already be on a personal/Business WhatsApp app). Then it's no longer limited to the recipient allow‑list.
• Business verification — Meta requires verifying your business to raise messaging limits and go fully live. Start it under Business Settings → Security Center.
• Message templates — to message a customer outside the 24h window (e.g. OrderPin Broadcasts), you must use a pre‑approved template. Create them under Notifications → WhatsApp templates and submit for Meta approval.
• A stable webhook URL — in production the webhook lives at your deployed domain (e.g. https://api.yourdomain.com/api/v1/whatsapp/webhook/), not a tunnel. Set it once in Meta and you're done.