Add a backend endpoint to this project that generates a WhatsApp signup link
from the Pilot Status API.

Create a server-side route: POST /api/pilot/pairing-session

It must accept a JSON body: { "customerId": string, "customerName": string }
where customerId is the id of the logged-in customer in this app's own database.

The route must call the Pilot Status API server-side:

  POST https://pilotstatus.com.br/v1/numbers/remote-pairing
  Headers:
    Content-Type: application/json
    x-api-key: <the value of the PILOT_TENANT_KEY environment variable>
  Body:
    {
      "provider": "META",
      "metaFlow": "embedded",
      "name": "<customerName>",
      "externalRef": "<customerId>"
    }

A successful response is HTTP 201 with exactly this shape:

  {
    "provider": "META",
    "remotePairingUrl": "https://connect.pilotstatus.com.br/connect/<token>",
    "expiresAt": "2026-07-20T18:30:00.000Z"
  }

The signup token is the LAST PATH SEGMENT of remotePairingUrl. Extract it with
new URL(remotePairingUrl).pathname.split("/").pop(). The token is valid for 30
minutes.

Store a row in this app's database before responding: { customerId, token,
expiresAt, status: "pending" }. You will need to match the result back to this
customer later.

Respond to the frontend with ONLY { token, expiresAt }. Never return the raw
Pilot Status response and never return the API key.

CRITICAL SECURITY REQUIREMENTS — do not deviate:

- The Pilot Status API key starts with "ps_" and is a server-side secret. Read
  it ONLY from a server environment variable named PILOT_TENANT_KEY.
- NEVER put the key in frontend code, and NEVER name the variable with a
  public prefix: not VITE_, not NEXT_PUBLIC_, not REACT_APP_, not PUBLIC_.
  Those prefixes ship the value inside the browser bundle where any user can
  read it.
- NEVER call pilotstatus.com.br from browser code. Its CORS policy is a strict
  allowlist of Pilot Status's own domains, so a browser request from this app's
  origin will be blocked. Generating the link is the ONLY Pilot Status call in
  this whole integration, and it happens here, on the backend.
- Do not log the API key or the token.

Optionally, the request body sent to Pilot Status also accepts a "branding"
object that styles the hosted button. Include it only if I ask for it:

  "branding": {
    "button": {
      "variant": "facebook",   // or "dark" | "light" | "outline"
      "label": "Connect WhatsApp",
      "primaryColor": "#1877F2",
      "textColor": "#FFFFFF",
      "radius": "md",          // "sm" | "md" | "lg" | "pill"
      "size": "md",            // "sm" | "md" | "lg"
      "fullWidth": true
    }
  }

All branding fields are optional. Styling is accepted ONLY inside this signed
token request — there is no query parameter for it, so do not try to pass
colors or labels on the iframe URL.

Add a "Connect WhatsApp" section to the customer-facing page of this app that
embeds the Pilot Status hosted signup button in an iframe.

Behaviour:

1. When the customer clicks "Connect WhatsApp", call this app's own backend:
   POST /api/pilot/pairing-session with { customerId, customerName }.
   It responds with { token, expiresAt }.

2. Render an iframe with this exact src:

   https://connect.pilotstatus.com.br/connect/<token>?embed=1&mode=button&parentOrigin=<origin>

   where <token> is URL-encoded and <origin> is
   encodeURIComponent(window.location.origin).
   The mode=button parameter renders only the Facebook button — no header, no
   card, transparent background — so it drops into your own layout.

3. The iframe MUST have this sandbox attribute, exactly:

   sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"

   allow-popups and allow-popups-to-escape-sandbox are MANDATORY. The Facebook
   login popup opens from inside the iframe. Without these two flags the popup
   is blocked silently: no error, no console message, the button just appears
   to do nothing. This is the single most common failure in this integration.

4. Style the iframe: width 100%, border: 0, display: block, and a starting
   height of 48px. Do not set a background colour on it.

5. Register a window "message" listener to receive events from the iframe.
   Validate EVERY message before using it — both checks, every time:

   - event.origin must be exactly "https://connect.pilotstatus.com.br"
   - event.data.source must be exactly "pilot-status-embed"

   Ignore any message that fails either check and return early. (Optionally, also
   require event.source === iframe.contentWindow for extra hardening.)

   Each message is an object shaped like this — only "type" is at the top level,
   everything else is inside "payload":

     { source: "pilot-status-embed", v: 1, type: "<event name>", payload: { ... } }

   Branch on message.type and read the data from message.payload. The events are
   "connect:paired" (payload has numberId, phone, displayName, provider,
   externalRef, redirectUrl), "connect:error" (payload.message),
   "connect:expired" (no payload), and "resize" (payload.height).

6. Handle the "resize" event: payload is { height: number }. Set the iframe's
   style.height to that many pixels. The hosted page emits this continuously so
   the iframe fits its content with no scrollbar.

7. Remove the listener when the component unmounts.

Do NOT load any Facebook SDK in this app, do NOT call FB.login anywhere, and do
NOT fetch /api/health or any other Pilot Status endpoint from the browser. The
hosted iframe does ALL of the Facebook work — the SDK, the popup, the app id and
config — on a domain that is already registered with Meta. Running any of that on
this app's own domain would require registering this domain with Meta, which is
not possible here.

Do not call pilotstatus.com.br from this frontend code for any reason — CORS
blocks it. The only network call the frontend makes is to this app's own
backend.

Extend the window "message" listener added for the Pilot Status signup iframe
to handle the three result events. Keep the existing origin and source
validation checks — apply them before anything below.

Event: type === "connect:paired"
The customer finished signup successfully. The payload is:

  {
    numberId:    string | null,   // the Pilot Status number id
    phone:       string | null,   // the connected phone number, digits
    displayName: string | null,   // WhatsApp display name
    provider:    string | null,   // "META" for this flow
    externalRef: string | null,   // the customerId sent when generating the link
    redirectUrl: string | null    // optional post-connect URL, if you set one
  }

Every field is always present but any of them can be null, so never assume a
value is there and never crash on a missing one. Do NOT auto-navigate to
redirectUrl — the iframe leaves that decision to you.

On this event:
  - POST the payload to this app's own backend at POST /api/pilot/paired.
  - Hide the iframe and show a success state with the phone number.

Event: type === "connect:error"
Payload is { message: string }. Show that message to the customer and offer a
retry button that requests a fresh token from your backend and re-renders the
iframe.

Event: type === "connect:expired"
The token passed its 30-minute lifetime. Do not reuse it. Show "This link
expired" and a button that requests a fresh token from your backend and
re-renders the iframe.

Backend: add POST /api/pilot/paired.

It must NOT trust externalRef from the request body to decide which customer
this belongs to — a browser can send anything. Instead:

  - Identify the customer from the authenticated session on the request.
  - Look up the pending row this app stored when it generated the link
    (the one with status "pending" for that customer).
  - Update it to: { numberId, phone, displayName, provider, status: "connected",
    connectedAt: now }.
  - Treat externalRef from the payload as a cross-check only: if it does not
    match the stored customerId, log a warning and do not save.

Make this handler idempotent — the same numberId may arrive twice. Match on
numberId and update rather than inserting a duplicate row.

Keep the Pilot Status API key out of all of this. Nothing in this step calls
pilotstatus.com.br.

Add webhook registration to this app so it receives inbound WhatsApp messages
for each connected number.

Step 1 — register the webhook, server-side.

After a number is connected (in the POST /api/pilot/paired handler, once
numberId is known), call the Pilot Status API from the backend:

  POST https://pilotstatus.com.br/v1/webhooks
  Headers:
    Content-Type: application/json
    x-api-key: <the PILOT_TENANT_KEY environment variable, server-side only>
  Body:
    {
      "url": "https://<this app's public URL>/api/pilot/webhook",
      "whatsappNumberId": "<the numberId from the paired event>",
      "events": ["messages"]
    }

The "events" array is REQUIRED in practice. Nothing is delivered unless events
contains a matching event name or the wildcard "*". An empty array, or omitting
the field, means this app receives absolutely nothing — and there is no error
to tell you so. Always send an explicit events array.

Step 2 — receive the deliveries.

Add a public route: POST /api/pilot/webhook

CRITICAL — the payload format for a META number is Meta's NATIVE envelope, not
a Pilot Status event. It looks like this:

  {
    "object": "whatsapp_business_account",
    "entry": [
      {
        "id": "<waba id>",
        "time": 1753027200,
        "changes": [
          { "field": "messages", "value": { ...Meta's message payload... } }
        ]
      }
    ]
  }

Parse it by reading body.entry[0].changes[0].field and branching on that value.
Inbound messages arrive under field === "messages", with the actual messages in
value.messages[] and contacts in value.contacts[].

Do NOT write a handler that looks for an event named "message.received". A META
number NEVER sends that. "message.received" belongs to a different, unofficial
number type. Subscribing with events: ["*"] does not translate the payload
either — it is always Meta's native envelope for a META number.

Other things to get right:

- A webhook created via POST /v1/webhooks has no secret, so these deliveries
  carry NO signature header — do not write signature verification and do not
  assume the request is authenticated. (If a secret is later set on the webhook,
  deliveries include an x-pilot-status-signature header holding an HMAC-SHA256 of
  the raw request body; only verify it once you have actually set a secret.) Use
  an unguessable path segment in the webhook URL, or an IP allowlist, if you need
  to harden it.
- Return HTTP 200 immediately, then process asynchronously. Failed deliveries
  are retried 5 times with exponential backoff starting at 5 seconds, so slow
  or failing handlers cause duplicates.
- Make the handler idempotent — deduplicate on the message id from Meta's
  payload.
- The webhook URL must be publicly reachable over HTTPS. A localhost or
  preview-only URL will never receive anything.