Embed the Connect Page

​

Token shape and TTL

​

Flow

curl -X POST "https://pilotstatus.com.br/v1/numbers/remote-pairing" \
  -H "x-api-key: ps_your_tenant_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "META",
    "metaFlow": "embedded",
    "name": "Support",
    "externalRef": "crm-customer-4821",
    "redirectUrl": "https://app.yoursaas.com/whatsapp/done",
    "branding": { "primaryColor": "#1877F2" }
  }'

curl -X POST "https://pilotstatus.com.br/v1/numbers/remote-pairing" \
  -H "x-api-key: ps_your_tenant_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support",
    "number": "5511999999999",
    "branding": { }
  }'

{
  "provider": "PILOT_STATUS",
  "instance": { "id": "…", "instanceName": "…", "number": "5511999999999", "displayName": "Support", "state": "CLOSE" },
  "remotePairingUrl": "https://connect.pilotstatus.com.br/connect/<token>",
  "maskedNumber": "+5511****9999",
  "linkedApiKeyId": null,
  "warnings": ["redirectUrl is only supported for provider=META and was ignored"]
}

<script src="https://pilotstatus.com.br/embed.js"></script>
<script>
  PilotStatus.init();
  const { token } = await fetch("/api/my-saas/pairing-token").then(r => r.json());

  // Centered modal:
  const h = PilotStatus.connect.open({
    token,
    onPaired: (d) => { save(d.numberId, d.externalRef); h.destroy(); },
    onError: (e) => alert(e.message),
    onExpired: () => { /* mint a new link */ },
  });

  // or inline:
  // PilotStatus.connect.mount("#connect-widget", { token, onPaired, onError, onExpired });
</script>

​

Button mode

​

Which mode a link renders

PilotStatus.connect.mount("#connect-button", {
  token,                 // Meta token, metaFlow: "embedded"
  mode: "button",
  onPaired: (d) => save(d.numberId, d.externalRef),
  onError: (e) => console.error(e.message),
  onExpired: () => refreshToken(),
});

<iframe
  src="https://connect.pilotstatus.com.br/connect/<token>?embed=1&mode=button&parentOrigin=https://app.yoursaas.com"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
  style="width:100%;border:0;display:block"
></iframe>

​

Button styling (token only)

curl -X POST "https://pilotstatus.com.br/v1/numbers/remote-pairing" \
  -H "x-api-key: ps_your_tenant_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "META",
    "metaFlow": "embedded",
    "branding": {
      "primaryColor": "#0F172A",
      "button": {
        "variant": "whatsapp",
        "label": "Connect WhatsApp",
        "icon": "whatsapp",
        "radius": "pill",
        "size": "lg",
        "height": 56,
        "width": 320
      }
    }
  }'

• variant: "whatsapp" paints the button WhatsApp green (#25D366).
• icon is an inline brand glyph (SVG, no network call) drawn before the label; it inherits the text color. Omit it and it follows the variant: facebook → the Facebook glyph, whatsapp → the WhatsApp glyph, any other variant → no glyph at all. Send icon: "none" to drop it explicitly.
• height is applied as a min-height — the label never clips — and replaces the vertical padding that size would have given the button.
• width overrides fullWidth: when width is present, fullWidth is ignored. Without width, the button fills its container by default; set fullWidth: false to shrink it to its content.
• Validate before you call. Every bound in the table is enforced when you mint the link: a value outside the allowed range or enum makes POST /v1/numbers/remote-pairing answer 400 Validation error with a details breakdown, and nothing is created — no token, no link, no placeholder. A height of 1000 is a rejected request, not a button silently clamped back to the height implied by size.

​

The “secured by pilotstatus.com.br” marker

• Framed button mode hides it automatically. The page checks whether it is actually inside a frame (window.parent !== window); if it is, the marker is dropped. No token field, no switch, nothing to ask for — embed the button and it is already gone.
• Top-level button mode keeps it, deliberately. A lone, tenant-styled login button sitting on a *.pilotstatus.com.br URL with nothing identifying whose page it is, is precisely the surface Safe Browsing flags as deceptive. The marker is what keeps that URL attributable, so it stays whenever the button is not embedded.
• The full page always keeps it, including when hidePilotStatusBranding is set.

​

postMessage protocol (iframe → parent)

​

Plan slots and the delete-on-abandon pattern

PilotStatus.connect.mount("#connect-button", {
  token,
  mode: "button",
  onPaired: (d) => save(d.numberId, d.externalRef),
  onError: () => {
    // Cancel or failure — the button is still on screen for a retry, so mark the
    // attempt as abandoned and let your own UI decide when to give up.
    markPairingAbandoned(customerId);
  },
});

• The numberId claim inside the Meta token. Split the JWT on . and base64url-decode the middle segment — a metadata read of a token you minted yourself, no signature check needed.
• The numberId field on connect:paired — but that only arrives on success, so it is no help for the abandoned case.

​

connect:paired payload

{
  "numberId": "wn_9f3c21ab",
  "phone": "5511999999999",
  "displayName": "Support",
  "provider": "META",
  "externalRef": "crm-customer-4821",
  "redirectUrl": "https://app.yoursaas.com/whatsapp/done"
}

• numberId is the id you use everywhere else in the API (GET /v1/numbers/{id}, webhooks, sending).
• externalRef is whatever you passed when minting — join it against your own customer record. It is carried by Meta links; on QR pairing it arrives as null.
• All six fields — numberId, phone, displayName, provider, externalRef, redirectUrl — are always present: a flow that cannot know one sends null, never omits it, so you do not need per-path branching over them.
• redirectUrl, when present, is not followed while embedded — the iframe hands it to you and lets your page decide whether and where to navigate, instead of blowing out of the frame.

​

White-label / branding

​

Security model

• x-api-key stays on your backend; only it calls POST /v1/numbers/remote-pairing.
• The pairing token authorizes only that link’s pairing endpoints, and expires — 30 minutes for a Meta token, 24 hours for a QR pairing token.
• Origins are validated on both sides; the iframe runs on connect.* so its API calls are same-origin (no CORS surface for your app).
• Anything that changes how the page looks to an end-user is authenticated: it comes from a token minted with your key, never from a URL a stranger can type.

​

Related

• Embed the Chat Inbox
• Connect Numbers