# Coesistenza: API WhatsApp e app Business

URL: https://wa.genuka.com/it/docs/guides/coexistence
Language: Italian

> 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/phone-numbers));
la coesistenza è l'eccezione pensata per l'app WhatsApp Business
([Meta, Onboard WhatsApp Business app users](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users/)).

| Il tuo numero oggi                            | Cosa fare                                                                                                                                                                             |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sull'app **WhatsApp Business**                | Non 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 WhatsApp                       | Niente da liberare: viene registrato direttamente sulla Cloud API, senza app.                                                                                                         |

> [!WARNING]
> **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](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users/)),
  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](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/overview)).

## Come collego un numero in coesistenza a Genuka WA?

1. ### Apri il link di connessione

   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](https://wa.genuka.com/it/docs/onboarding).
   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**.

2. ### 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.

3. ### 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.

4. ### 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.

```bash title="GET /api/v1/numbers?refresh=true"
curl "https://wa.genuka.com/api/v1/numbers?refresh=true" \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY"
```

```json title="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](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users/)).
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](https://wa.genuka.com/it/docs/webhooks).

## 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 connessione                                                                                  | Tramite l'API                                                                                    |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Chat individuali                                               | Continuano a funzionare; modificare o revocare un messaggio è supportato                                      | Nuovi messaggi rispecchiati in entrambe le direzioni; cronologia precedente non ancora importata |
| Contatti                                                       | Invariati                                                                                                     | Nessuna importazione iniziale; aggiunte e modifiche successive annunciate da Meta                |
| Gruppi                                                         | Invariati                                                                                                     | Non sincronizzati                                                                                |
| Messaggi effimeri                                              | Disattivati nelle chat individuali                                                                            | No                                                                                               |
| Messaggi visualizzabili una volta                              | Disattivati nelle chat individuali                                                                            | No                                                                                               |
| Posizione in tempo reale                                       | Disattivata nelle chat individuali                                                                            | No                                                                                               |
| Liste broadcast                                                | Disattivate; le liste esistenti diventano di sola lettura                                                     | No                                                                                               |
| Chiamate vocali e video                                        | Invariate                                                                                                     | No                                                                                               |
| Catalogo, ordini, stato                                        | Invariati                                                                                                     | No                                                                                               |
| Risposte rapide, etichette, messaggi di assenza e di benvenuto | Invariati                                                                                                     | No                                                                                               |
| 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users/),
  [Meta, Throughput](https://developers.facebook.com/documentation/business-messaging/whatsapp/throughput)).
  Genuka adegua il ritmo delle tue [campagne](https://wa.genuka.com/it/docs/guides/campaigns-api) 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users/)).
* **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](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users/)).

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

* Meta — [Onboard WhatsApp Business app users](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users/)
* Meta — [Business phone numbers](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/phone-numbers)
* Meta — [Throughput](https://developers.facebook.com/documentation/business-messaging/whatsapp/throughput)
* Meta — [Partners (Tech Providers and Solution Partners)](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/overview)
* Genuka — [Guida SDK alla coesistenza](https://wa.genuka.com/sdk/coexistence)
