Onboarding ospitato (il tuo cliente collega il suo numero)

POST /v1/onboarding-links

Quando il numero è del tuo cliente e non vuoi chiedergli le sue credenziali di Meta, è lui stesso a collegare il suo WhatsApp in una pagina con il tuo marchio — senza login, senza vedere il nostro marchio, senza che tu tocchi l'app di Meta. Ci sono due modi, scegli il tuo:

1. Mandagli un link (senza codice). Generi il link dal pannello (Numeri → 'Invia un link a un cliente') e glielo passi tu (via WhatsApp, email, come preferisci). Ideale per collegare i clienti uno alla volta. Non devi scrivere niente.

2. Integralo nel tuo sistema (con codice). Il tuo cliente tocca 'Collega WhatsApp' dentro il TUO prodotto e si collega da solo, senza che tu intervenga. Il flusso: il tuo backend chiama POST /v1/onboarding-links con label, externalId (e returnOrigin se userai un popup) → riceve un url → lo mandi lì con un reindirizzamento (il più robusto, consigliato su mobile) o un popup (sembra integrato). Quando finisce, il risultato ti arriva via postMessage E tramite il webhook connection.created con il tuo externalId. Lo snippet di frontend e gli esempi di backend sono qui sotto.

In entrambi i casi puoi fissare la modalità (cloud_api/coexistence; se la ometti, la pagina collega in Coexistence senza offrire una scelta) e la lingua della pagina (lang: es/it/en/pt, oppure omettila per rilevarla dal browser). Il token è monouso e scade: la scadenza è configurabile (expiresIn in secondi, da 5 min a 30 giorni) — via API il valore predefinito è 1 ora, dal pannello 7 giorni.

curl -X POST https://api.waiaconnect.com/v1/onboarding-links \
  -H "Authorization: Bearer wc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"López Pharmacy","externalId":"pharmacy-42","lang":"es","returnOrigin":"https://app.yourcompany.com","expiresIn":3600}'
# → { "url": "https://…/c/<token>", "expiresAt": "…", "publicId": "onb_…" }
# Send url to your customer. It is shown ONCE; the token is consumed only when they connect.

// Call this from YOUR backend when your customer taps "Connect WhatsApp".
const res = await fetch("https://api.waiaconnect.com/v1/onboarding-links", {
  method: "POST",
  headers: { "Authorization": "Bearer wc_live_YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
  "label": "López Pharmacy",
  "externalId": "pharmacy-42",
  "lang": "es",
  "returnOrigin": "https://app.yourcompany.com",
  "expiresIn": 3600
})
});
const { url } = await res.json(); // https://…/c/<token> — hand this to the browser (redirect or popup)

<?php
// Call this from YOUR backend when your customer taps "Connect WhatsApp".
$ch = curl_init("https://api.waiaconnect.com/v1/onboarding-links");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer wc_live_YOUR_API_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["label" => "López Pharmacy","externalId" => "pharmacy-42","lang" => "es","returnOrigin" => "https://app.yourcompany.com","expiresIn" => 3600]),
]);
$out = json_decode(curl_exec($ch), true);
echo $out["url"]; // https://…/c/<token> — hand this to the browser (redirect or popup)

import requests
# Call this from YOUR backend when your customer taps "Connect WhatsApp".
res = requests.post("https://api.waiaconnect.com/v1/onboarding-links",
  headers={"Authorization": "Bearer wc_live_YOUR_API_KEY", "Content-Type": "application/json"},
  json={"label":"López Pharmacy","externalId":"pharmacy-42","lang":"es","returnOrigin":"https://app.yourcompany.com","expiresIn":3600})
res.raise_for_status()
print(res.json()["url"])  # https://…/c/<token> — hand this to the browser (redirect or popup)

Generi un link con il marchio del tuo cliente; lui collega il suo numero senza entrare nel tuo pannello né vedere il nostro marchio. Ricevi connection.created con il tuo externalId. Il dettaglio completo (diagramma, snippet del popup, e perché mai in un iframe) è dentro il pannello, con i tuoi dati reali.

L'URL (con il token) viene restituito UNA sola volta, come una API key — mandalo e salvalo.

Il token si consuma solo quando viene creata la connessione, non quando si apre la pagina. Se il tuo cliente chiude la finestra o gli salta la connessione a internet, riapre lo STESSO link e continua — finché non scade.

Il webhook è la fonte affidabile. Il postMessage si perde se il tuo cliente chiude la finestra; il webhook connection.created no. Conferma lato server con quell'evento.

⚠ Mai dentro un iframe: lì il popup di Embedded Signup si rompe (restrizioni sui popup + blocco dei cookie di terze parti). Usa un reindirizzamento o un popup di primo livello.

Per il popup, returnOrigin è obbligatorio: è l'origine https esatta a cui rispondiamo (mai *), validata quando crei il link.

Il tuo cliente non vede MAI il nostro marchio né entra nel tuo pannello; tu non entri MAI nel suo account Meta. Configura il tuo marchio in Impostazioni → Marchio.

Stati del link: pending (non usato), used (ha già collegato), expired (scaduto), revoked (l'hai annullato tu). Revoca un link in sospeso con DELETE /v1/onboarding-links/:id.

Sezione Link del pannello: lì vedi quelli che hai mandato (di entrambi i tipi), a quale cliente, quando scadono e a che punto sono — non aperto / aperto e non completato / completato. Un link senza attività era ambiguo: non c'era modo di distinguere "non l'ha visto" da "si è bloccato nel modulo", che richiedono azioni diverse.

🔒 Dell'apertura registriamo solo che è avvenuta e quando (la prima, l'ultima e quante volte). Niente del visitatore: né IP, né browser, né referer. GET /v1/onboarding-links restituisce engagement, firstOpenedAt, lastOpenedAt e openCount.

Dal pannello puoi copiare di nuovo l'URL di un link ancora valido (owner/admin, con registro di audit). Quello di un link usato/scaduto/revocato non viene mostrato: non servirebbe a niente.