WhatsApp Coexistence: usa l'API senza rinunciare a WhatsApp Business

Quale problema risolve

Prima della coesistenza (Coexistence), passare un numero all'API significava toglierlo dall'app: il team smetteva di rispondere dal telefono e bisognava migrare tutto su un sistema nuovo. Con Coexistence non devi scegliere: lo stesso numero, lo stesso account e le stesse conversazioni, nell'app e nel tuo sistema contemporaneamente.

Serve quando il numero esiste già, ci sono già clienti che scrivono e qualcuno risponde dal cellulare, e vuoi aggiungere automazione, un CRM o un bot senza interrompere quel servizio.

Come si collega

L'onboarding avviene con Embedded Signup, la finestra ufficiale di Meta. Il titolare del numero accede con Facebook, sceglie o crea il suo portafoglio aziendale e, alla fine, scansiona un codice QR dall'app WhatsApp Business (Impostazioni → Dispositivi collegati). Serve un secondo schermo: il codice appare sul computer e si scansiona con il telefono.

Puoi fare l'onboarding tu stesso dal pannello, oppure mandare al tuo cliente un link di onboarding con il tuo marchio, così lo fa lui senza darti le sue credenziali di Meta.

Passo per passo e cosa di solito lo blocca: Mentre ti colleghi · dove si scansiona il QR.

Cosa vede il tuo sistema

• I messaggi in arrivo (message.received), con un solo webhook per tutti i tuoi numeri.
• Ciò che il tuo team scrive dal telefono (message.echo): il contenuto di quei messaggi arriva al tuo sistema e non consuma la quota del tuo piano.
• Lo stato di ogni invio (message.status: inviato, consegnato, letto, non riuscito).
• I messaggi che il contatto modifica o elimina (message.edited, message.revoked): la versione finale, con l'id dell'originale.
• La cronologia delle tue chat, se la scegli al collegamento (history.batch e history.completed), oltre al riepilogo che Meta condivide al collegamento (history.synced).

Tutti gli eventi e il loro formato: Tipi di evento · Ricevere il webhook.

La cronologia delle tue conversazioni

WAIA Connect consegna la cronologia al tuo sistema se lo scegli al momento del collegamento. Prima di aprire la finestra di Meta ti chiediamo «Vuoi che ti consegniamo la cronologia delle tue conversazioni?» e devi rispondere sì o no; vale per tutti i piani.

La scelta è adesso: Meta condivide la cronologia una sola volta, quando colleghi il numero, e se scegli di no dopo non si può più richiedere. Se rispondi sì, WAIA Connect la scarica e la conserva cifrata; quando l'app WhatsApp Business te lo chiede, accetta di condividere la cronologia.

• Cosa contiene: fino a 6 mesi, con i messaggi di entrambe le parti di ogni conversazione, senza gruppi. La cronologia resta sul telefono: lì non si cancella né si sposta nulla.
• Foto, audio e documenti: arrivano senza il file (come media_placeholder). Meta invia il file solo degli ultimi 14 giorni, a parte e non sempre; se arriva, porta il suo id e si scarica con GET /v1/media/{id} entro 7 giorni. Ognuno dice qual è il suo caso in connect.media: disponibile fino a una data, o non disponibile e perché (più di 14 giorni · Meta non è riuscita a recuperarlo · in attesa).
• Come ti arriva: via webhook, nell'evento history.batch (un blocco di fino a 500 messaggi per evento, firmato come gli altri) e history.completed quando non resta nulla; oppure tramite l'API, con GET /v1/connections/{id}/history (a pagine) e POST /v1/connections/{id}/history/{batchId}/ack per confermare ogni blocco. Per riceverla serve un webhook o usare l'API.
• Quanto la conserviamo: cifrata, 7 giorni al massimo. Si cancella appena te la consegniamo (un 2xx del tuo webhook o la conferma tramite l'API); ciò che non è stato consegnato si cancella comunque dopo 7 giorni. Se il quinto giorno non l'hai ancora ricevuta, ti avvisiamo nel pannello e via email, con la data in cui verrà cancellata.
• A che ritmo: passa da una coda separata, per non rallentare i messaggi in tempo reale, e può richiedere ore. Non conta come traffico né consuma la quota del tuo piano.
• Un blocco può arrivare due volte: deduplica per batchId.
• Se restassimo senza spazio, smetteremmo di conservare nuova cronologia e te lo diremmo nel pannello e con l'evento history.dropped. Il riepilogo history.synced continua ad arrivare come sempre.

Limiti della coesistenza (secondo Meta)

Sono di Meta, non di WAIA Connect, e valgono con qualsiasi fornitore. La documentazione ufficiale di Meta dice che, dopo aver collegato un numero in coesistenza:

• L'app deve essere WhatsApp Business 2.24.17 o successiva.
• Le liste broadcast e i messaggi «visualizza una volta» vengono disattivati; gruppi, messaggi effimeri, posizione in tempo reale e chiamate tramite l'API non sono supportati.
• Meta condivide fino a 6 mesi di cronologia, una sola volta, al collegamento, e senza i gruppi. Se l'hai scelto, WAIA Connect la consegna al tuo sistema (dettagli sopra).
• Il numero ha un limite di 20 messaggi al secondo.
• I dispositivi collegati vengono scollegati al collegamento e bisogna ricollegarli; la documentazione indica eccezioni per piattaforma.
• Se il telefono principale non viene usato per circa 14 giorni, Meta scollega il numero.

I messaggi inviati dall'app restano gratuiti; quelli inviati tramite l'API hanno i prezzi abituali di Meta.

Quanto costa

Una tariffa fissa per numero collegato, senza limite di messaggi e con 14 giorni di prova:

• Starter — US$ 12 al mese, 1 numero
• Studio — US$ 25 al mese, 5 numeri
• Agencia — US$ 45 al mese, 12 numeri
• Escala — US$ 99 al mese, 30 numeri, più US$ 3 per ogni numero extra

Meta addebita a parte i propri messaggi, sulla carta del tuo account Meta; WAIA Connect non aggiunge ricarichi. Dettagli nell'Aiuto.

Domande frequenti

Posso continuare a rispondere dal cellulare dopo aver collegato il numero all'API?

Sì. Con Coexistence l'app WhatsApp Business continua a funzionare sul telefono, e ciò che si scrive lì arriva al tuo sistema come evento message.echo.

Perdo le mie chat quando mi collego?

No: restano sul telefono, e lì non si cancella né si sposta nulla. Se al collegamento scegli di ricevere la cronologia, WAIA Connect chiede a Meta fino a 6 mesi e la consegna al tuo sistema via webhook (history.batch) o tramite l'API, entro 7 giorni. La scelta è adesso: Meta la condivide una sola volta, al collegamento, e nell'app devi accettare di condividerla. Altrimenti, dal momento del collegamento ricevi i messaggi nuovi.

Il mio cliente deve darmi il suo accesso a Facebook?

No. Gli mandi un link di onboarding con il tuo marchio, lui fa l'onboarding nella finestra di Meta con la sua sessione, e il numero resta collegato al tuo account WAIA Connect.

Cosa non funziona in coesistenza?

Secondo Meta: liste broadcast, messaggi «visualizza una volta», gruppi, messaggi effimeri, posizione in tempo reale e chiamate tramite l'API. Il numero ha un limite di 20 messaggi al secondo.

Fa per me se non ho intenzione di programmare nulla?

Probabilmente no: WAIA Connect collega WhatsApp a un tuo sistema. Se vuoi una casella per rispondere con il tuo team e un assistente di IA, senza programmare, quello è WAIA.

Fonti

Consultate il 28/09/2026.

• Meta — Onboarding WhatsApp Business app users (Coexistence)

Per continuare

• Cloud API o Coexistence: quale scegliere
• Embedded Signup: l'onboarding ufficiale di Meta
• Il limite di 300 nuove chat dell'app
• Documentazione dell'API
• Aiuto
• Informativa sulla privacy