Skip to main content
I workspace Switchbord non sono più limitati a un singolo Account WhatsApp Business (WABA). Un workspace può fare l’onboarding di WABA aggiuntivi tramite il flusso Embedded Signup di Meta — il popup di accesso ospitato direttamente da Meta — senza mai dover gestire un access token copiato manualmente. Ogni WABA ottiene il proprio slot di credenziali isolato, così un secondo (o terzo) numero non sovrascrive mai il primo.
Embedded Signup è additivo. Il wizard originale “porta il tuo token” su /welcome è rimasto invariato ed è sempre disponibile — Embedded Signup è un secondo percorso opzionale per i workspace che preferiscono un onboarding ospitato da Meta invece di incollare un token System User.

​
Tre percorsi di onboarding

Quando Embedded Signup è abilitato, /welcome presenta un selettore (OnboardingPathChooser) con tre card invece di passare direttamente al wizard manuale: Scegliere “Fai l’onboarding con noi” o “Migra un account WhatsApp esistente” renderizza entrambi lo stesso EmbeddedSignupCard — l’unica differenza è il valore path (onboard vs migrate) inviato all’endpoint di scambio, e la UI di signup di Meta adatta il proprio testo di conseguenza. Una casella di controllo Abilita Messaggi di Marketing appare quando è configurato un config ID Meta con ambito marketing, e determina quale config_id di login Facebook viene utilizzato.
Ogni schermata del selettore ha un pulsante “Scegli un metodo diverso” per tornare indietro, così un operatore che avvia Embedded Signup e incontra un vicolo cieco (ad blocker, popup chiuso, errore Meta) può sempre ricorrere al wizard manuale del token senza ricaricare la pagina.

​
Feature flag e prerequisiti

Embedded Signup è disattivato per impostazione predefinita ed è vincolato sia a un flag client pubblico sia a credenziali dell’app lato server: Il controllo lato server è deliberatamente una difesa a più livelli: attivare da solo il flag client non può mai esporre un flusso Embedded Signup funzionante senza che anche le credenziali dell’app siano configurate.

​
Come funziona lo scambio

  1. Il browser carica una volta il Facebook JS SDK (connect.facebook.net/en_US/sdk.js) e chiama FB.login() con il config_id risolto, richiedendo un code di autorizzazione.
  2. Il popup di Meta invia anche un evento postMessage WA_EMBEDDED_SIGNUP (validato rispetto a un’origine facebook.com / *.facebook.com) che trasporta il waba_id e il phone_number_id selezionati dall’operatore all’interno della UI di Meta.
  3. Una volta arrivati entrambi il code e la coppia WABA/telefono, la card invia (POST) una sola volta a /api/onboarding/meta/exchange con { code, wabaId, phoneNumberId, path, includeMarketingMessages }.
  4. La route (apps/app/app/api/onboarding/meta/exchange/route.ts) esegue una sequenza rigorosa lato server:
    • scambia il code con un access token business (exchangeEmbeddedSignupCode);
    • ispeziona il token con debugToken e richiede sia lo scope whatsapp_business_management che whatsapp_business_messaging;
    • se gli scope granulari di Meta enumerano gli ID WABA concessi, il wabaId fornito deve trovarsi in quella lista — un WABA id fornito dal client non è mai considerato attendibile alla cieca;
    • conferma che il numero di telefono appartenga effettivamente a quel WABA tramite listWabaPhoneNumbers prima di fare qualsiasi altra cosa;
    • genera e memorizza un PIN di registrazione a 6 cifre usa e getta (segreto meta-phone-pin) e chiama registerPhoneNumberForCloudApi — un fallimento di registrazione Meta (già registrato, mismatch 2FA in migrazione) viene tollerato e riportato come phoneRegistered: false invece di far fallire l’intera richiesta;
    • genera un token di verifica per workspace e sottoscrive l’app Switchbord al WABA con un override_callback_uri ambitato per workspace (.../webhooks/meta?w=<workspaceId>);
    • risolve in quale slot di credenziali rientra il token di questo WABA (vedi sotto), memorizza il token e importa il numero di telefono in un canale.
  5. La risposta non contiene mai l’access token, il PIN, il verify token, META_APP_SECRET, né alcun appsecret_proof — solo channelId, wabaId, phoneNumberId, displayName, phoneRegistered e marketingMessagesEnabled.
La route di scambio applica un invariante rigoroso contro la fuoriuscita di segreti: i campi detail nelle risposte di errore possono contenere esclusivamente il messaggio di errore già sanificato di Meta. Token, PIN, verify token e l’app secret non vengono mai registrati nei log, catturati nella telemetria delle eccezioni, né rimandati al browser.

​
Isolamento del token Multi-WABA

Prima di questo lavoro, il token Meta di ogni workspace viveva sotto un unico tipo di segreto Vault (meta-access-token) — un secondo WABA collegato tramite Embedded Signup sovrascriveva silenziosamente il token del primo WABA e interrompeva i suoi invii. Switchbord ora risolve il token di ogni WABA in modo indipendente:
  • L’account provider predefinito (il primo WABA in un workspace, o uno già contrassegnato come predefinito) continua a usare il tipo di segreto meta-access-token — i workspace con un solo WABA non sono affatto interessati.
  • Ogni WABA aggiuntivo occupa il primo slot libero da meta-access-token-2 a meta-access-token-8 (allocateWabaTokenSlotKind), registrato su whatsapp_provider_accounts.credential_secret_kind. Otto slot superano comodamente qualsiasi conteggio realistico di WABA per workspace.
  • resolveChannelAccessToken(admin, { workspaceId, channelId | channel }) è il risolutore unico usato da ogni percorso critico di invio (dispatch dei messaggi — che copre anche gli invii di campagna — invii di media, invii interattivi e sincronizzazione dei template). Risolve canale → account provider → credentialSecretKind, legge quello slot Vault, e ricade sul meta-access-token predefinito del workspace e poi sulla variabile d’ambiente WHATSAPP_META_ACCESS_TOKEN se lo slot è vuoto. Non lancia mai un’eccezione per un token mancante — i chiamanti fanno fallire il dispatch in modo esplicito esattamente come prima.
Questo è trasparente per gli operatori — non esiste un campo token per WABA da gestire nelle Impostazioni. Il tipo di slot viene scelto automaticamente al momento dell’onboarding e letto automaticamente al momento dell’invio. Settings → Provider continua a mostrare solo i tipi di credenziali rivolti all’operatore; i tipi di slot WABA sono interni.

​
Verificare un workspace Multi-WABA

  • Controlla whatsapp_provider_accounts per il workspace: la riga predefinita ha is_default = true e credential_secret_kind = 'meta-access-token'; ogni WABA aggiuntivo ha il proprio slot credential_secret_kind e is_default = false.
  • Un invio per un WABA non predefinito che segnala il numero mittente sbagliato significa quasi sempre che il credential_secret_kind del suo account provider è mancante o punta allo slot sbagliato — verifica che setProviderAccountCredentialKind sia stato chiamato durante l’onboarding di quel WABA.
  • Se Embedded Signup è stato completato ma phoneRegistered è tornato false, il numero di telefono è collegato al canale ma non è ancora registrato per gli invii Cloud API — completa la registrazione dalle Impostazioni prima di aspettarti che gli invii vengano effettuati.

​
Vedi anche