How to Set Up WhatsApp Flows Checkout

WhatsApp Flows are multi-screen experiences inside WhatsApp (catalog pick → fulfillment → date/address → payment).

ProfilePilot B2C retail checkout Flow (`pp_retail_checkout_v1`) creates the same `whatsapp_orders` rows as conversational chat.

Use Flows when you want a structured UI; keep chat checkout for quick reorders and AI browse.

Requires:

• WhatsApp Commerce + retail catalog mirrored to `whatsapp_products` (run catalog sync first)
• Encrypted data_exchange endpoint on ProfilePilot
• RSA keypair signed on the same phone_number_id that sends templates

Open WhatsApp Orders → Flows:

1. Click Generate keypair (stored encrypted per org).
2. Copy the endpoint URL — format:

`https://profilepilotapp.com/api/whatsapp/flows?org_id=<your-org-uuid>`

1. Click Sign public key on Meta (uses connected `phone_number_id`).

Critical: `org_id` in the URL must match the organisation whose keypair you signed. Mixing Actonia lab keys with a client org breaks decryption (health check 421 Decryption failed).

Verify keypair runs an encrypted ping against Meta.

Reference Flow JSON for Manager import lives in the repo: `docs/whatsapp_flow_retail_checkout.json`.

Screen ids: `CATALOG` → `FULFILLMENT` → `DATE` or `ADDRESS` → `PAYMENT`. Responses use `"version": "3.0"`.

In WhatsApp Manager → Flows:

1. Create Flow → Endpoint type (not fully static Navigate-only).
2. Paste endpoint URL with correct `org_id`.
3. Import screens from ProfilePilot JSON or rebuild matching screen ids.
4. Publish Flow and link it to a MARKETING template button (category Marketing) or test from Manager.

Manager “Send flow” test:

• Choose Request data (not “No data”) so INIT loads catalog from ProfilePilot.
• Pick the connected business phone number.

Empty product dropdown usually means: catalog sync not run, products `is_available = false`, or wrong org in endpoint URL.

Create template in Manager on the client WABA:

• Category: MARKETING
• Button: Flow
• Flow starts with → Network request (Data exchange) — not “Pre-defined screen → Choose items”

ProfilePilot campaign send supplies `flow_token` only (`pp.v1.<base64url>`). Do not add `flow_action` on template sends — Graph rejects unexpected keys.

Sync template in Marketing → WhatsApp → Sync templates, then compose a campaign with that template.

For manual API debugging, build token via ProfilePilot Flows card or server helper for the target org + recipient WA id.

INIT `data_exchange` returns available products from `whatsapp_products` as dropdown entries:

• id = SKU (stable for Meta 30-char limits)
• title = product name truncated to 30 characters

Checkout resolves SKU → internal UUID when completing the order.

Product images in Flow dropdown are not in V1 (text-only Dropdown). Chat product cards still show `image_url`.

Always return `"error_message": ""` on success responses (Meta UI expectation).

| Issue | Fix | | --- | --- | | Manager test works, template send fails | Template must use Network request; campaign uses synced APPROVED MARKETING template | | `flow_action` Graph error | Remove flow_action from template payload — send flow_token only | | Empty catalog | Sync catalog; confirm org_id; products available | | 421 Decryption failed | Regenerate keys on production domain; re-sign on same phone_number_id | | Duplicate orders | Same flow_token is idempotent — check `whatsapp_orders.flow_token` unique index | | Payment screen missing methods | Configure Payments tab for org |

After submit, order appears in WhatsApp Orders → Kitchen Queue like chat checkout. Sprint 7 (Lead/Survey flows → Smart Inbox) is separate from retail checkout.