`docs/whatsapp-golive-runbook.md`

49 lines
# WhatsApp Cloud API — go-live runbook (Costa Rica marketplace)

Goal: turn the already-built WhatsApp client (`lib/whatsapp.js` — text, template,
interactive, media, location, receipts, inbound webhook) from sandbox to LIVE by
**reusing Steve's existing Meta app `9851…`** (the one powering Norma/Instagram).
No new Meta app, no new business verification.

## What only Steve can do (one time, ~10 min)
1. Log into **business.facebook.com** (the account that owns app `META_APP_ID=9851…`).
2. **Add the WhatsApp product** to that app → creates a **WhatsApp Business Account (WABA)**.
3. **Add a phone number** to the WABA (must NOT be on personal WhatsApp; a fresh
   number or a Twilio number works) and verify it via SMS/voice code.
4. Copy the **Phone number ID** and generate a **permanent System-User token**
   (Business Settings → System users → generate token → scopes `whatsapp_business_messaging`,
   `whatsapp_business_management`).

> Or say **"drive it"** — after step 1 (your login in openclaw Real Chrome), the
> `portal-driver` skill does steps 2–4 and captures the Phone ID + token.

## What I auto-finish the moment those two values exist
```bash
# Steve pastes: WHATSAPP_TOKEN + WHATSAPP_PHONE_ID
#  (WHATSAPP_APP_SECRET is already in secrets as META_APP_SECRET=76ad…; reuse it)
node ~/Projects/costa-rica/scripts/whatsapp-golive.js   # verifies + registers webhook + test send
```
The script:
1. Routes the two values via the **`secrets`** skill → `costa-rica/.env`
   (`WHATSAPP_TOKEN`, `WHATSAPP_PHONE_ID`, `WHATSAPP_APP_SECRET=<META_APP_SECRET>`,
   `WHATSAPP_VERIFY_TOKEN=<random>`).
2. **Verifies** the token via `GET /{PHONE_ID}?fields=verified_name,display_phone_number`.
3. **Subscribes** the app to the WABA + registers the webhook
   `https://costarica.agentabrams.com/webhooks/whatsapp` (verify token from step 1).
4. Sends a **test template** to Steve's number to confirm delivery.
5. Restarts pm2 `costa-rica --update-env` → `lib/whatsapp.js` flips `liveMode=true`
   → every booking confirmation + two-way chat is now real.

## Message-template note (Meta requirement)
Proactive messages outside the 24h session window MUST be **pre-approved templates**.
Submit these in Business Manager (one-time approval, ~minutes to hours):
- `booking_confirmed` (es/en) — "✅ Reserva confirmada {{1}} · {{2}}"
- `booking_reminder` (es/en) — check-in reminder
- `payout_sent` (es/en) — host payout notice
Free-form text/interactive replies are allowed within 24h of a user's inbound message.

## Status
- Client + webhook: **built & sandbox-tested** ✅
- Reuse of app `9851…` + `META_APP_SECRET`: **confirmed available** ✅
- Blocking on: WABA phone number + system-user token (Steve, above) 🔴