π For SaaS / multi-tenant platforms reselling WhatsApp to clients. Copy and paste into Cursor, Codex, Claude, or any AI coding assistant.
"Please build a complete multi-tenant integration for a WhatsApp Automation SaaS using the WasapFlow Bridge API as our backend provider. Read and strictly follow the full documentation available at these URLs:
- https://partner.wasapflow.com/bridge/docs?tab=api
- https://partner.wasapflow.com/bridge/docs?tab=guide
- https://partner.wasapflow.com/bridge/docs?tab=changelog
ALWAYS read the changelog URL above first. It lists breaking changes and Meta platform changes with their effective dates. Build against what it says is current, not against older examples you may have seen elsewhere.
The system architecture must be divided into TWO main sections (Superadmin/Partner Settings and End-User Site):
1. SUPERADMIN / PARTNER SETTINGS SITE:
- REQUIRED: Create an "API Credentials" configuration page/tab. Display a CLEAR, prominent note reminding the developer/admin to copy-paste TWO (2) core credentials from their WasapFlow Partner Dashboard:
1. Partner Key (Save securely in the DB or environment variables as WF_PARTNER_KEY)
2. Webhook Secret (Save securely in the DB or environment variables as WF_WEBHOOK_SECRET)
- Ensure the system securely stores and encrypts these credentials in the database.
- Create a Client WABA Monitoring Dashboard displaying a table/list with the following columns: WABA Name | Phone Number ID | Total API Requests (with a monthly auto-reset mechanism) | Meta Quality Status (GREEN/YELLOW/RED).
- Include a "View Error Logs" action button/modal for each client that displays raw error details (Meta Error Code & Message) if an API request fails or if a 'message.failed' webhook event is captured.
2. END-USER SITE (CUSTOMER PORTAL):
- Create a "Connect WhatsApp" module using the "WasapFlow Hosted Popup" method. When clicked, it must open the WasapFlow connection URL in a popup window, listen for the 'WASAPFLOW_CONNECT_SUCCESS' window postMessage, and securely send the returned 'code' to our backend for automated registration (via the /clients/register-from-code endpoint) using connection_mode: "coexistence".
- Build an inbound Webhook Listener endpoint (POST /webhook/whatsapp). The backend MUST strictly verify the request's authenticity by validating the 'x-wasapflow-signature' header against the stored 'WF_WEBHOOK_SECRET' before processing any payload.
- Properly route inbound events: handle 'message.received' to capture customer chat messages into our live chat database, and update message delivery logs using 'sent', 'delivered', and 'read' status updates.
- π BSUID FUTURE-PROOFING: For every customer contact, store BOTH the phone number ('data.from') AND the Business-Scoped User ID ('data.bsuid', format 'MY.xxx') in the database. BSUID is a stable identifier that persists across WhatsApp username adoption (Meta rollout June 2026). Use BSUID as the customer's primary lookup key when available; fall back to phone otherwise. The same advice applies to status webhooks where 'data.recipient_bsuid' is provided alongside 'data.recipient'.
- π COEXISTENCE SYNC: Because clients connect with connection_mode "coexistence", they may also reply to customers directly from the WhatsApp Business App on their phone. Handle the 'message.echo' event (data.direction "outbound", data.source "business_app") and save it as an OUTBOUND message in the live chat so our inbox mirrors WhatsApp exactly β never treat it as an inbound customer message. Also handle the 'message.history' event (data.history === true), which Meta replays ONCE after onboarding to backfill the client's past conversations: route these into a history/backfill path, order them using data.timestamp (the ORIGINAL message time), and DO NOT trigger auto-replies, bots, or notifications on historical messages. You may use data.phase / data.progress (0β100) to show a "syncing historyβ¦" indicator. Also handle 'contact.synced' (data.action add/update/remove) to keep each client's contact list in sync when they edit contacts in the Business App β upsert/delete by data.phone_number.
- π TEMPLATE LIFECYCLE: If clients create message templates through our platform, handle the template webhooks so they always know a template's real state before sending. On 'template.status_updated' (data.status APPROVED/REJECTED/PENDING/PAUSED/DISABLED, data.reason on rejection) update the template's status in our DB and only allow sending APPROVED templates. Also handle 'template.quality_updated' (data.previous_quality β data.new_quality; GREEN/YELLOW/RED) and 'template.category_updated' (data.new_category, may affect pricing) β surface these in the client's template dashboard.
- π’ WABA HEALTH: Handle 'waba.account_updated' (data.event e.g. VERIFIED_ACCOUNT, DISABLED_UPDATE, ACCOUNT_RESTRICTION) and 'waba.review_updated' (data.decision APPROVED/REJECTED) to monitor each client's account standing. Flag or pause clients whose WABA gets disabled/restricted, and alert the admin dashboard. These join the existing 'waba.quality_updated' and 'waba.tier_updated' events.
- Create a "WhatsApp Business API Usage & Billing Analytics" dashboard for the end-user. Render clear metrics mapping message usage status (Sent, Delivered, Read, Failed) derived from incoming webhook data.
- π° COST TRACKING (IMPORTANT β Meta starts charging more on 1 October 2026): Every message status webhook ('message.sent', 'message.delivered', 'message.read', 'message.failed') carries an optional 'data.pricing' object { billable, pricing_model, type, category } plus 'data.conversation' { id, origin }. Persist ALL of these per message, and treat them as OPTIONAL and null-safe because Meta omits them on some events (commonly 'read'). The 'pricing.type' field is the one that matters: 'regular' is billable today; 'free_customer_service' is free today but BECOMES BILLABLE ON 1 OCTOBER 2026 (this covers both non-template service replies and utility templates sent inside the 24-hour window); 'free_entry_point' stays free. Build a per-client monthly report counting messages grouped by pricing.type and pricing.category so each client can see their upcoming cost exposure before charging starts. Do NOT hardcode any rate β Meta publishes the new rates by 1 September 2026 and rates differ by country.
- π’ PLATFORM NOTICES: Every Bridge API response includes headers 'X-Bridge-Api-Version', 'X-Bridge-Changelog', 'X-Bridge-Notice' (comma-separated stable notice IDs) and 'X-Bridge-Notice-Level' ('info' | 'action_required' | 'breaking'). Every webhook body carries the same inside a 'meta' object. Log these and raise an admin alert when the level is 'action_required' or 'breaking', so we learn about Meta platform changes before they take effect rather than after. Notice IDs are stable, so allow suppressing ones already handled.
- π€ REQUIRED β META BUSINESS AGENT STANDBY BANNER: If a client enables Meta Business Agent on their WhatsApp number, Meta's AI becomes the active handler and Meta STOPS sending 'message.received' to us, sending 'standby.message_received', 'standby.message_echo' and 'standby.message_status' instead. The client's automation appears to die with no error and nothing in our logs. You MUST handle this: (1) On ANY event whose name starts with 'standby.' β or where data.standby === true β do NOT auto-reply. Sending a message during standby makes our app the active handler and causes two AIs to fight over one conversation. Store the message for conversation context only. (2) Raise a PERSISTENT WARNING BANNER for that client, shown BOTH in the app header AND at the top of that number's inbox. Style it as a WARNING (yellow/amber) not an error β nothing is broken. Wording: "π€ Meta Business Agent is answering your customers β not your AI. To take back control, turn it off in WhatsApp Manager β Account tools β Business Agent. Manual chat still works normally." (3) Make raising the banner IDEMPOTENT β standby events can arrive many times a minute, so create/update one alert record per phone_number_id rather than notifying per event. (4) CLEAR the banner automatically when a normal 'message.received' event arrives again for that number, which means we are the active handler once more.
- π LOG UNRECOGNISED WEBHOOK EVENTS: Our webhook handler will be a chain of checks on the event name, which means any NEW event Bridge or Meta introduces falls through SILENTLY - no error, no log, nothing, and we find out months later when a client reports something odd. Add a final fallback branch: if an incoming event name is not one we explicitly handle, log it ONCE with the full payload, then throttle repeats (e.g. log again only at 2, 4, 8, 16 occurrences so a high-volume event cannot flood the logs). This is how we learn about new Meta capabilities in days instead of months.
- π PHONE NUMBER IS NOT THE WHATSAPP ID (REQUIRED by Meta): Do NOT assume a customer's WhatsApp number is their phone number. After WhatsApp usernames, Meta may omit the phone entirely and send only a BSUID like 'MY.2035200694071263' (fields 'wa_id'/'from'/'recipient_id' are omitted when the user has a username and has not interacted for 30 days). A BSUID can send WhatsApp messages but a COURIER CANNOT CALL IT. Therefore: (1) Store TWO separate fields per contact - a canonical id (phone OR bsuid, used for sending WhatsApp and matching the contact) and a reachable phone (always a real phone, may be empty, used for courier/invoice/voice). (2) In phone validation, DETECT and REJECT BSUID - never normalise it. Pattern: /^(?:whatsapp:)?[A-Z]{2}\.(?:ENT\.)?[A-Za-z0-9]{1,128}$/. The usual normaliser replace(/\D/g,'') then prepending a country code turns 'MY.2035200694071263' into '602035200694071263', which LOOKS like a valid Malaysian number, passes naive checks and reaches the courier silently. Return null instead - no number beats a fake one. (3) In the order collection flow, ASK the customer for a phone number as a required field alongside name and address. When we already hold a plausible number, ask them to CONFIRM it (one-word answer, minimal friction): "Boleh sahkan no 012-345 6789 ni untuk kurier WhatsApp atau call ya?". When we have nothing, ask them to provide it: "Boleh bagi no telefon untuk kurier WhatsApp atau call masa hantar ya?". Newest number always wins so corrections stick. (4) When pushing to WooCommerce or any ERP, send the REAL phone as billing.phone and keep the canonical id in a SEPARATE meta field so status/tracking webhooks can still match the contact back. Leave billing.phone EMPTY rather than filling it with an id.
- πͺ HANDLE ALL THREE POPUP OUTCOMES: The connect popup posts back to window.opener on success, cancel AND failure - 'WASAPFLOW_CONNECT_SUCCESS' (waba_id, phone_number_id, display_name, quality_rating, connection_mode), 'WASAPFLOW_CONNECT_CANCEL' (reason) and 'WASAPFLOW_CONNECT_ERROR' (message, code). All three carry the 'state' we passed when minting the link. Verify event.origin is https://officialapi.wasapflow.com, then IGNORE any message whose 'state' does not match the client this UI is connecting - a popup left open for one client must never register against another. Do not leave the UI stuck in a connecting state waiting only for success: before Bridge 2.6.1 cancel and error were never posted at all, so any handler written against an older version never fired. Keep a 'popup.closed' poll as a safety net, since a customer can still close the window before any message is sent.
- π NEVER PUT THE PARTNER KEY IN A BROWSER URL: The onboarding link must be created server-side with POST /bridge/v1/connect/session (authenticated with the x-partner-key header), which returns a 'connect_url' carrying a 30-minute token. Open THAT url in the client's browser. Do NOT build '/bridge/connect?partner_key=...' in frontend code or in a link the client can see - partner_key is the full API credential for every WABA and every send, and a URL leaks it into browser history, the Referer header sent to other hosts, and server access logs in plain text. Pass an optional 'state' (max 255 chars) to that endpoint and it is returned untouched when onboarding completes, in the postMessage payload and in the register-from-code response, so the finished connection can be matched to our own client record. If our code currently builds the partner_key link, migrate it and then rotate the key in the partner portal - a key that has been through a browser must be treated as exposed.
- π€ SENDING TO A CUSTOMER WITH NO PHONE NUMBER: From Bridge 2.5.0 every send endpoint accepts the recipient under 'to', 'user_id' or 'recipient', and a BSUID is routed correctly whichever you use - so you can simply put the canonical id in 'to' and stop branching. When a phone number and a BSUID are both supplied the phone number wins (Meta's rule). ON 2.4.0 THIS WAS NOT TRUE: a BSUID placed in 'to' was forwarded to Meta's phone field, stripped to digits, and failed with 131026 'Message undeliverable' AFTER Bridge had already returned 2xx - so if you are pinned to 2.4.0 you must use 'recipient'. ALWAYS record the wamid from the send response: it is returned as BOTH 'message_id' and 'messages[0].id' (same value), and every message.sent/delivered/read/failed callback is keyed on it - without it a message.failed cannot be matched to anything and a silent non-delivery looks like success forever. IMPORTANT: a send to a BSUID returns contacts[0].user_id and NO wa_id, so any code reading wa_id from a send response must read user_id for BSUID sends. Meta REJECTS BSUID recipients for one-tap, zero-tap and copy-code AUTHENTICATION templates - Bridge 2.5.0 returns HTTP 400 AUTH_TEMPLATE_NEEDS_PHONE (meta_code 131062, retryable false). This is permanent: do not retry it, collect a real phone number instead.
- π§ DO NOT BUILD WHAT BRIDGE ALREADY EXPOSES: as of 2.9.0 there are 68 endpoints, not the dozen most integrations use. Before writing a workaround or emailing support, check the API reference for: QR codes and short links (/qr-codes), ice breakers and slash-commands (/conversational-automation), blocking spam numbers (/blocked), showing or hiding the catalog and cart (/commerce-settings), call and No-Storage settings (/settings), whether a number is an Official Business Account or has 2FA on (/phone-status), the WABA audit log for 'why did this template disappear' (/waba/activities), and the phone number lifecycle (/phone/request-code, /phone/verify-code, /phone/two-step, /phone/register, /phone/deregister). Irreversible calls need {"confirm": true} or they return 400 CONFIRMATION_REQUIRED. If we have ever changed the two-step PIN outside Bridge, set it once via POST /phone/two-step - otherwise WasapFlow's re-registration of our numbers will fail silently during a recovery.
- π¦ READ META ERROR CODES, NOT MESSAGE TEXT: error responses carry meta_code, meta_subcode and details alongside message. Branch on meta_code - Meta rewords messages without warning. Know these three: 131047 re-engagement required (user has not messaged in 24h, retry only after they do), 131062 AUTHENTICATION template to a BSUID (permanent, get a real phone number), and 131000 on any /groups call which means Groups is not enabled on that number by Meta (not a Bridge fault, not retryable). On POST and DELETE /blocked an HTTP 200 does NOT mean every number succeeded - Meta reports per-number failures in a 'failed' array, so read both arrays.
- π€ EVERY FIELD IS snake_case, REQUESTS AND RESPONSES ALIKE: waba_id, phone_number_id, access_token, display_name, quality_rating, messaging_limit_tier, registered_at. There is NO camelCase form of this API. Do not write wabaId or phoneNumberId anywhere - those properties are never present and reading them silently yields undefined, so a WABA can look registered while we store nothing usable. An older version of our documentation showed a camelCase response example; it was wrong and has been corrected.
- π DO NOT SET A GRAPH API VERSION ANYWHERE: Bridge owns it and currently calls Meta on v26.0, with all 32 webhook fields on v26.0 too. Bridge normalises every webhook into its own event envelope, so Meta's version is never visible to us. Never call graph.facebook.com directly - we do not hold the Meta token, Bridge does.
CODING & CONFIGURATION RULES:
- API BASE URL: Securely HARDCODE this official production base URL directly into the system configuration: https://officialapi.wasapflow.com/bridge/v1
- THERE IS NO WASAPFLOW SDK. Do not run npm install / pip install / composer require for one, and do not invent an import for it. Bridge is plain REST: two headers (x-partner-key, and x-waba-id on anything acting on a specific client's number), JSON in, JSON out. Use whatever HTTP client this project already has - fetch, axios, Guzzle, requests, httpx. Write ONE small wrapper function that takes (path, method, wabaId, body) and reuse it for all 68 endpoints; that is the whole abstraction needed.
- The webhook listener must ALWAYS immediately return an HTTP 200 OK response within 10 seconds before initiating asynchronous background processing to prevent webhook retries.
- Never hardcode or expose any Meta permanent access tokens (EAAxxxx) on the frontend. All token exchanges and handshakes must remain strictly server-to-server via WasapFlow Bridge."