Genuka WA docs

Coesistenza: API WhatsApp e app Business

Tieni l'app WhatsApp Business sul tuo numero mentre usi l'API: requisiti (2.24.17+), passaggi di onboarding, cosa si sincronizza e i limiti.

Sì, puoi usare l'API WhatsApp senza abbandonare l'app WhatsApp Business: è la coesistenza di Meta. Con l'app alla versione 2.24.17 o successiva, colleghi lo stesso numero a Genuka WA, continui a rispondere a mano dal telefono e invii in volume tramite l'API. I nuovi messaggi nelle conversazioni individuali compaiono da entrambe le parti.

Ultimo aggiornamento: 8 ottobre 2026

Il mio numero può usare la coesistenza?

Dipende dall'app su cui gira oggi il numero. Meta non registra sulla Cloud API un numero già in uso su WhatsApp a meno che non venga prima eliminato (Meta, Business phone numbers); la coesistenza è l'eccezione pensata per l'app WhatsApp Business (Meta, Onboard WhatsApp Business app users).

Il tuo numero oggiCosa fare
Sull'app WhatsApp BusinessNon eliminare nulla. Aggiorna l'app e collega il numero: Meta propone la coesistenza durante la registrazione, l'app continua a funzionare e le tue conversazioni vengono conservate.
Su WhatsApp (l'app normale, non Business)Liberalo prima: elimina l'account WhatsApp su quel numero, oppure collega un altro numero. La coesistenza copre solo l'app WhatsApp Business.
Su nessuna app WhatsAppNiente da liberare: viene registrato direttamente sulla Cloud API, senza app.

Non eliminare mai un account WhatsApp Business per collegarti

Eliminare l'account dell'app Business ne distrugge la cronologia, ed è inutile: la coesistenza esiste proprio perché quel numero possa restare com'è.

Cosa ti serve prima di iniziare

  • Un account Facebook. Meta ti chiede di accedere con questo; va bene un account personale.
  • L'app WhatsApp Business alla versione 2.24.17 o successiva (Meta), sul telefono che ha il numero, a portata di mano: la connessione si conferma dall'app.
  • Per inviare modelli in seguito, un metodo di pagamento sul tuo WhatsApp Business Account: Genuka è un Tech Provider, quindi Meta fattura direttamente il tuo account (Meta, Partners).

Come collego un numero in coesistenza a Genuka WA?

Dalla tua dashboard, nella pagina Numeri (o Link di connessione se gestisci clienti), oppure dal tuo link pubblico /connect/{your-slug}: vedi Collegare un numero. Genuka mostra prima una breve checklist: account Facebook, numero su WhatsApp Business (non WhatsApp normale), telefono in mano con l'app aggiornata. Spunta tutte e tre le voci, poi clicca Sono pronto: apri Meta.

Scegli la tua app WhatsApp Business esistente

Nella finestra di Meta, accedi con Facebook e scegli o crea il portafoglio aziendale. Genuka apre l'Embedded Signup con l'opzione di onboarding dell'app WhatsApp Business, così Meta propone di collegare il tuo account esistente invece di crearne uno nuovo. Inserisci il numero: la finestra di Meta resta poi in attesa di un codice di verifica.

Conferma dal telefono

Nell'app WhatsApp Business arriva un messaggio dall'account ufficiale "Facebook Business". Tocca Connect, poi Connect to the Business Platform, poi Confirm: è il passaggio in cui Meta propone di condividere la cronologia delle chat (Genuka WA non la importa ancora, vedi sotto). Copia il codice di verifica.

Completa nella finestra di Meta

Incolla il codice e completa il flusso. Tornato su Genuka, la connessione viene finalizzata: l'account e il numero compaiono nel tuo workspace, l'account WhatsApp viene iscritto ai webhook e il numero non viene registrato di nuovo sulla Cloud API: è Meta stessa a registrarlo in coesistenza.

Una volta collegato, chiama una volta GET /api/v1/numbers?refresh=true. Genuka legge allora il numero da Meta e ne registra la modalità di coesistenza; senza questa chiamata, l'elenco predefinito ("source": "database") mostra ancora coexistence: false per un numero appena collegato.

GET /api/v1/numbers?refresh=true
curl "https://wa.genuka.com/api/v1/numbers?refresh=true" \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY"
Risposta (estratto)
{
  "data": [
    {
      "id": "con_1",
      "displayPhoneNumber": "+237 6 90 00 00 01",
      "platformType": "SMB_APP",
      "coexistence": true,
      "messagesPerSecond": 20,
      "status": "connected",
      "metaStatus": "CONNECTED",
      "refreshed": true
    }
  ],
  "source": "meta"
}

La risposta completa contiene anche, per ogni numero, gli alerts di stato rilevati durante la lettura e un oggetto limits con i throughput di riferimento. Un aggiornamento interroga Meta numero per numero e si ferma a 25 numeri per chiamata: oltre, restringi con ?companyId=.

La cronologia della mia app viene importata?

Per ora no. Meta invia i contatti e la cronologia dell'app solo se il provider li richiede, entro le 24 ore successive alla connessione; trascorso questo tempo, il numero va scollegato e il flusso ripetuto (Meta). Genuka WA non fa ancora questa richiesta. In pratica:

  • Le tue conversazioni passate restano nell'app, intatte, ma non compaiono in Genuka WA. Meta consente di importare le conversazioni individuali degli ultimi 180 giorni, senza i gruppi (stessa pagina); Genuka WA oggi non lo fa.
  • Tutto ciò che arriva dopo la connessione passa invece: i messaggi ricevuti su message.received, i messaggi inviati tramite l'API e quelli che scrivi nell'app (vedi sotto).
  • I contatti aggiunti o modificati in seguito nell'app vengono annunciati da Meta via webhook (stessa pagina); Genuka li inoltra su coexistence.contacts_synced: vedi Webhook.

Cosa si sincronizza e cosa no?

Secondo la pagina di Meta sulla coesistenza, con quello che Genuka WA ne fa oggi:

FunzionalitàNell'app dopo la connessioneTramite l'API
Chat individualiContinuano a funzionare; modificare o revocare un messaggio è supportatoNuovi messaggi rispecchiati in entrambe le direzioni; cronologia precedente non ancora importata
ContattiInvariatiNessuna importazione iniziale; aggiunte e modifiche successive annunciate da Meta
GruppiInvariatiNon sincronizzati
Messaggi effimeriDisattivati nelle chat individualiNo
Messaggi visualizzabili una voltaDisattivati nelle chat individualiNo
Posizione in tempo realeDisattivata nelle chat individualiNo
Liste broadcastDisattivate; le liste esistenti diventano di sola letturaNo
Chiamate vocali e videoInvariateNo
Catalogo, ordini, statoInvariatiNo
Risposte rapide, etichette, messaggi di assenza e di benvenutoInvariatiNo
Dispositivi collegati (WhatsApp Web, ecc.)Scollegati alla connessione, da ricollegare in seguito; WhatsApp per Windows e per WearOS non sono supportati—

Cosa cambia per gli invii via API?

  • Il throughput è fissato a 20 messaggi al secondo su un numero in coesistenza, contro gli 80 predefiniti sulla Cloud API (Meta, coexistence, Meta, Throughput). Genuka adegua il ritmo delle tue campagne non appena il numero è registrato come in coesistenza (la chiamata ?refresh=true qui sopra). Un lancio è anche limitato nel tempo: tieni le campagne a qualche centinaio di destinatari (vedi i limiti nella guida alle campagne).
  • I messaggi inviati dall'app restano gratuiti; quelli inviati tramite l'API seguono i prezzi della Cloud API (Meta).
  • Ciò che scrivi sul telefono compare in Genuka. Meta inoltra questi messaggi (gli "echo"); Genuka li archivia nella conversazione, con l'etichetta "Inviato dall'app WhatsApp Business". Non consumano nulla del tuo piano e sono esclusi dalle statistiche di consegna, che contano solo ciò che ha inviato l'API: nessuna ricevuta di consegna li segue mai. Iscrizione webhook: coexistence.message_echoed.
  • I limiti di Meta si applicano come ovunque: modelli approvati fuori dalla finestra di 24 ore, il limite di messaggi del portafoglio aziendale, il limite marketing per utente.

Come scollego l'API dall'app?

La disconnessione avviene nell'app, non tramite l'API: Settings > Account > Business Platform, poi Disconnect Account (etichette come nella documentazione di Meta). Meta invia allora un webhook account_update con l'evento PARTNER_REMOVED (Meta).

Su Genuka, il numero passa allora a disconnected e l'API non può più inviare da esso. Nulla viene eliminato: messaggi, modelli e statistiche restano legati al numero. Ripassando dallo stesso link di connessione lo rimetti in servizio sullo stesso record, senza occupare un nuovo slot del tuo piano.

FAQ

Devo eliminare il mio account WhatsApp Business per usare l'API?

No. È proprio lo scopo della coesistenza: l'app continua a funzionare sullo stesso numero. Solo un numero usato su WhatsApp normale va liberato prima di collegarlo.

I messaggi inviati dal telefono contano sul mio piano Genuka?

No. Solo gli invii fatti tramite l'API o una campagna consumano la quota di messaggi del tuo piano. I messaggi scritti nell'app vengono sincronizzati perché la conversazione sia completa, senza essere conteggiati.

E se la mia app è più vecchia della 2.24.17?

Aggiornala prima di aprire la finestra di Meta. Meta richiede la versione 2.24.17 o successiva per proporre la coesistenza.

Posso continuare a usare WhatsApp Web?

Sì, dopo averlo ricollegato: i dispositivi collegati vengono scollegati alla connessione e si possono ricollegare, tranne WhatsApp per Windows e per WearOS.

Quanti messaggi al secondo posso inviare in coesistenza?

20, qualunque sia il tuo livello presso Genuka o presso Meta. È un tetto che Meta fissa per i numeri condivisi con l'app.

Fonti

In questa pagina