Connessione API WhatsApp Business: Come risolvere i problemi comuni

Guida alla risoluzione dei problemi per la configurazione della Coesistenza WhatsApp — idoneità del numero, restrizioni regionali, ritardi di sincronizzazione e altro.

W
WhatsTeam23 marzo 2026
Connessione API WhatsApp Business: Come risolvere i problemi comuni

Risoluzione Problemi WhatsApp Business API: Problemi Comuni di Configurazione e Soluzioni

La configurazione della WhatsApp Business API con la modalità Coesistenza può talvolta presentare delle sfide. Questa guida alla risoluzione dei problemi copre i problemi più comuni che potresti incontrare durante il processo di onboarding con WhatsTeam, insieme alle cause principali e alle istruzioni passo-passo per la risoluzione.

1. Idoneità del Numero di Telefono

Sintomo del Problema

Durante il flusso di Embedded Signup, ricevi un messaggio di errore che indica che il tuo numero di telefono non è idoneo per la registrazione con la WhatsApp Business API. Il numero viene rifiutato durante il passaggio di verifica e non puoi procedere con il processo di onboarding.

Numero di telefono non idoneo per la registrazione WABA
Numero di telefono non idoneo per la registrazione WABA

Causa Principale

Non tutti i numeri di telefono sono idonei per la registrazione alla WhatsApp Business API. Le ragioni comuni includono:

  • Il numero di telefono è già registrato con un altro provider di WhatsApp Business API (BSP)
  • Il numero di telefono è un numero fisso che non può ricevere SMS o chiamate vocali per la verifica
  • Il numero di telefono è stato precedentemente bannato o segnalato da WhatsApp
  • Il formato del numero è errato o include prefissi internazionali non validi
  • Il numero è un numero virtuale di un provider VoIP non supportato

Passaggi per la Risoluzione

  1. Verifica il formato del numero: Assicurati che il numero di telefono sia inserito nel formato internazionale completo, incluso il prefisso internazionale (es. +1 per USA, +34 per Spagna), senza zeri iniziali dopo il prefisso
  2. Controlla le registrazioni esistenti: Se il numero era precedentemente registrato con un altro BSP, devi prima annullarne la registrazione dal vecchio provider prima di registrarti con WhatsTeam
  3. Usa un numero mobile: Per la migliore esperienza, usa un numero di telefono cellulare in grado di ricevere codici di verifica SMS
  4. Prova la verifica vocale: Se la verifica SMS fallisce, seleziona l'opzione chiamata vocale per ricevere il codice di verifica tramite telefonata
  5. Contatta il supporto: Se il numero è stato precedentemente bannato o continui a riscontrare problemi, contatta il supporto WhatsTeam con i dettagli del tuo numero di telefono così possiamo indagare ulteriormente con Meta

2. Restrizioni Regionali

Sintomo del Problema

Quando tenti di registrare il tuo numero di telefono, vedi un errore che indica che il tuo paese o regione non è supportato per la registrazione alla WhatsApp Business API. Il flusso di Embedded Signup blocca la registrazione al passaggio dell'inserimento del numero di telefono.

Prefisso paese non supportato per WABA
Prefisso paese non supportato per WABA

Causa Principale

La WhatsApp Business API non è disponibile in tutti i paesi e regioni. Meta mantiene un elenco dei mercati supportati e i numeri di telefono con prefissi di regioni non supportate non possono essere registrati. Inoltre, determinate sanzioni o restrizioni normative possono impedire l'accesso all'API in paesi specifici.

Passaggi per la Risoluzione

  1. Controlla le regioni supportate: Rivedi l'elenco ufficiale dei paesi supportati per la WhatsApp Business API nella documentazione di Meta
  2. Usa un numero alternativo: Se il tuo paese principale non è supportato, considera l'utilizzo di un numero di telefono da una regione supportata dove la tua attività ha una presenza
  3. Verifica il prefisso: Ricontrolla di aver inserito il prefisso corretto per il tuo numero. Un prefisso errato potrebbe attivare un errore di restrizione regionale anche se il tuo paese effettivo è supportato
  4. Controlla le aggiunte recenti: Meta espande regolarmente le sue regioni supportate. Se il tuo paese è stato aggiunto di recente, riprova o svuota la cache del browser prima di riprovare
  5. Contatta il supporto WhatsTeam: Se ritieni che la tua regione dovrebbe essere supportata ma continui a riscontrare problemi, contatta il nostro team di supporto per assistenza

3. Utilizzo Precedente di WABA

Sintomo del Problema

Durante la registrazione, ricevi un errore che indica che il tuo numero di telefono è già associato a un WhatsApp Business Account (WABA). Il sistema ti impedisce di completare la registrazione perché il numero ha un'associazione API precedente.

Numero già verificato con un altro WABA
Numero già verificato con un altro WABA

Causa Principale

Un numero di telefono può essere associato a un solo account WhatsApp Business API alla volta. Se il numero è stato precedentemente utilizzato con:

  • Un altro BSP (Business Solution Provider)
  • Un diverso account Meta Business Manager
  • Un deployment self-hosted della WhatsApp Business API
  • Un precedente account WhatsTeam di cui non è stata correttamente annullata la registrazione

Il numero rimane bloccato su quell'associazione precedente fino a quando non viene formalmente deregistrato.

Passaggi per la Risoluzione

  1. Identifica il provider precedente: Determina quale BSP o piattaforma aveva il tuo numero registrato precedentemente. Controlla il tuo account Meta Business Manager per eventuali associazioni WABA esistenti
  2. Deregistra dal provider precedente: Contatta il BSP precedente e richiedi che deregistrino il tuo numero di telefono dal loro account WhatsApp Business API
  3. Rimuovi dal Meta Business Manager: Se hai accesso al Meta Business Manager dove il numero era registrato, vai alla sezione WhatsApp Manager ed elimina il numero di telefono
  4. Attendi la propagazione: Dopo la deregistrazione, attendi almeno 24 ore prima di tentare di registrare nuovamente il numero. In alcuni casi, potrebbe richiedere fino a 48 ore perché la deregistrazione si propaghi completamente
  5. Riprova la registrazione: Una volta trascorso il periodo di deregistrazione, riavvia il flusso di Embedded Signup in WhatsTeam e registra nuovamente il tuo numero
  6. Escalation se necessario: Se il numero rimane bloccato dopo 48 ore, contatta il supporto WhatsTeam con la prova di proprietà e noi escaleremo il problema direttamente con Meta

4. Ritardi nella Sincronizzazione

Sintomo del Problema

Dopo aver completato l'Embedded Signup e abilitato la modalità Coesistenza, la tua WhatsApp Business App non riflette la connessione API. Contatti, messaggi o informazioni del profilo aziendale non si sincronizzano tra la WhatsApp Business App e l'API. Lo stato della Coesistenza appare come "In attesa" per un periodo prolungato.

Causa Principale

La sincronizzazione tra la WhatsApp Business App e la Cloud API può subire ritardi a causa di:

  • Problemi di connettività di rete sul telefono che esegue la WhatsApp Business App
  • Grandi volumi di contatti o messaggi esistenti che devono sincronizzarsi
  • Ritardi di elaborazione lato server sull'infrastruttura di Meta
  • La WhatsApp Business App esegue una versione obsoleta
  • Restrizioni sulle app in background sul telefono che impediscono la sincronizzazione

Passaggi per la Risoluzione

  1. Controlla la connessione internet: Assicurati che il telefono che esegue la WhatsApp Business App abbia una connessione internet stabile, preferibilmente Wi-Fi
  2. Aggiorna l'app: Assicurati di eseguire l'ultima versione della WhatsApp Business App dall'App Store (iOS) o Google Play Store (Android)
  3. Chiudi forzatamente e riapri: Chiudi completamente la WhatsApp Business App e riaprila per avviare un nuovo tentativo di sincronizzazione
  4. Disabilita l'ottimizzazione della batteria: Su Android, vai su Impostazioni > Batteria > Ottimizzazione batteria e disabilitala per la WhatsApp Business App. Su iOS, assicurati che l'Aggiornamento app in background sia abilitato per l'app
  5. Attendi con pazienza: La sincronizzazione iniziale può richiedere fino a 24 ore per account con grandi liste di contatti o cronologie di messaggi. Concedi tempo sufficiente prima di considerare la sincronizzazione come fallita
  6. Riavvia il telefono: Un riavvio completo del dispositivo può risolvere problemi sottostanti di connettività o processo
  7. Riabilita la Coesistenza: Se la sincronizzazione fallisce ancora dopo 24 ore, prova a disabilitare e riabilitare la modalità Coesistenza tramite WhatsTeam. Vai alle impostazioni del dispositivo, disabilita la Coesistenza, attendi 5 minuti, quindi riabilitala

5. Problemi con il Codice QR

Sintomo del Problema

Durante la configurazione della Coesistenza, ti viene chiesto di scansionare un codice QR con la tua WhatsApp Business App, ma il codice QR non si carica, è scaduto o l'app non lo riconosce. La scansione del codice QR risulta in un errore o nessuna risposta.

Causa Principale

I problemi con il codice QR durante la configurazione della Coesistenza si verificano tipicamente a causa di:

  • Il codice QR è scaduto (i codici QR hanno un limite temporale e devono essere scansionati entro pochi minuti)
  • La cache del browser o dell'app mostra un codice QR vecchio o non valido
  • La versione della WhatsApp Business App non supporta la scansione QR della Coesistenza
  • I permessi della fotocamera non sono abilitati per la WhatsApp Business App
  • Il codice QR viene scansionato con l'app sbagliata (WhatsApp normale invece di WhatsApp Business)

Passaggi per la Risoluzione

  1. Aggiorna il codice QR: Clicca il pulsante di aggiornamento sulla schermata del codice QR in WhatsTeam per generare un nuovo codice QR valido. I codici QR scadono dopo circa 60 secondi
  2. Svuota la cache del browser: Svuota la cache del browser o prova ad aprire la dashboard di WhatsTeam in una finestra di navigazione in incognito/privata per assicurarti di vedere un codice QR aggiornato
  3. Aggiorna la WhatsApp Business App: Assicurati di eseguire l'ultima versione della WhatsApp Business App. Le funzionalità di Coesistenza richiedono la versione più recente dell'app
  4. Controlla i permessi della fotocamera: Sul tuo telefono, verifica che la WhatsApp Business App abbia il permesso di accedere alla fotocamera. Vai su Impostazioni del telefono > App > WhatsApp Business > Permessi > Fotocamera
  5. Usa l'app corretta: Assicurati di scansionare il codice QR con la WhatsApp Business App, non l'app WhatsApp normale. La modalità Coesistenza è disponibile solo sulla WhatsApp Business App
  6. Prova un dispositivo diverso: Se la fotocamera del tuo dispositivo principale ha problemi, prova a scansionare il codice QR con un dispositivo diverso che ha lo stesso account WhatsApp Business
  7. Controlla illuminazione e display: Assicurati che la luminosità dello schermo del computer sia sufficientemente alta e che non ci siano riflessi sullo schermo che potrebbero interferire con la scansione del codice QR

6. Errori di Connessione della Pagina Facebook

Sintomo del Problema

Durante il flusso di Embedded Signup, incontri un errore quando tenti di connettere il tuo WhatsApp Business Account a una Pagina Facebook Business. Il sistema non mostra pagine disponibili, visualizza un errore di permessi o non riesce a stabilire la connessione tra il tuo WABA e la Pagina Facebook.

Causa Principale

Gli errori di connessione della Pagina Facebook derivano tipicamente da:

  • Non hai accesso admin alla Pagina Facebook che stai tentando di connettere
  • La Pagina Facebook è già connessa a un diverso WhatsApp Business Account
  • Il tuo Meta Business Manager non ha la proprietà della Pagina Facebook
  • C'è una discrepanza tra il Meta Business Manager usato per il WABA e quello che gestisce la Pagina Facebook
  • La Pagina Facebook ha restrizioni o è stata annullata la pubblicazione

Passaggi per la Risoluzione

  1. Verifica l'accesso admin alla pagina: Conferma che il tuo account Facebook abbia accesso a livello di amministratore alla Pagina che vuoi connettere. Vai alla Pagina Facebook > Impostazioni > Ruoli della Pagina per verificare
  2. Controlla le connessioni esistenti: In Meta Business Manager, vai su Impostazioni Business > Account > Account WhatsApp per vedere se la Pagina è già collegata a un altro WABA. Disconnettila prima dall'altro account
  3. Usa il Business Manager corretto: Assicurati di aver effettuato l'accesso allo stesso account Meta Business Manager che possiede sia la Pagina Facebook che il WABA che stai configurando
  4. Rivendica la Pagina: Se la Pagina non fa ancora parte del tuo Meta Business Manager, vai su Impostazioni Business > Account > Pagine > Aggiungi e rivendica la proprietà della Pagina
  5. Crea una nuova Pagina: Se non riesci a risolvere i permessi su una Pagina esistente, crea una nuova Pagina Facebook Business tramite Meta Business Manager e usala per la connessione WABA
  6. Controlla lo stato della Pagina: Assicurati che la Pagina Facebook sia pubblicata e non soggetta a restrizioni. Le pagine non pubblicate o con restrizioni non possono essere connesse a WABA
  7. Contatta il supporto Meta: Se nessuno dei passaggi precedenti risolve il problema, contatta il Supporto Meta Business tramite il tuo Meta Business Manager per assistenza con i problemi di connessione della Pagina

7. Disabilitazione della Coesistenza

Sintomo del Problema

Vuoi disabilitare la modalità Coesistenza per utilizzare la WhatsApp Business API in modo indipendente (senza la WhatsApp Business App connessa), ma l'opzione per disabilitare è in grigio, produce un errore o il processo non si completa correttamente.

Causa Principale

La disabilitazione della Coesistenza può fallire a causa di:

  • Ci sono conversazioni attive o messaggi in attesa elaborati tramite la WhatsApp Business App
  • La WhatsApp Business App non è stata correttamente disconnessa dal telefono
  • Un blocco a livello di sistema è attivo mentre la sincronizzazione è ancora in corso
  • Permessi insufficienti in WhatsTeam per modificare le impostazioni del dispositivo
  • Limiti di frequenza dell'API o restrizioni temporanee del servizio da Meta

Passaggi per la Risoluzione

  1. Completa le sincronizzazioni in sospeso: Assicurati che tutta la sincronizzazione dei messaggi tra la WhatsApp Business App e l'API sia completata prima di tentare di disabilitare la Coesistenza
  2. Controlla i permessi: Verifica che il tuo account WhatsTeam abbia accesso a livello admin alle impostazioni del dispositivo. Solo gli utenti admin possono abilitare o disabilitare la modalità Coesistenza
  3. Disconnetti prima l'app: Sul tuo telefono, apri la WhatsApp Business App e scollega tutti i dispositivi connessi prima di disabilitare la Coesistenza in WhatsTeam
  4. Attendi e riprova: Se il sistema mostra una sincronizzazione in corso, attendi almeno 30 minuti prima di riprovare. Tentare di disabilitare durante una sincronizzazione attiva può causare errori
  5. Cancella la sessione: In WhatsTeam, vai alle impostazioni del dispositivo e cancella tutte le sessioni attive prima di disabilitare la Coesistenza
  6. Contatta il supporto: Se l'opzione di disabilitazione rimane non disponibile o continua a dare errore, contatta il supporto WhatsTeam. In alcuni casi, la Coesistenza potrebbe dover essere disabilitata dal backend di Meta, il che richiede che il nostro team si coordini con Meta

8. Incompatibilità del Dispositivo Companion

Sintomo del Problema

Dopo aver abilitato la modalità Coesistenza, tenti di utilizzare la WhatsApp Business App su un dispositivo companion (come un tablet o un secondo telefono), ma il dispositivo companion non riesce a connettersi, mostra errori o non riceve i messaggi correttamente.

Causa Principale

La modalità Coesistenza ha limitazioni specifiche riguardo ai dispositivi companion:

  • Il supporto dei dispositivi companion della WhatsApp Business App è limitato a determinati tipi di dispositivo e versioni del sistema operativo
  • Il dispositivo principale deve rimanere connesso e attivo affinché i dispositivi companion funzionino
  • C'è un numero massimo di dispositivi companion consentiti (tipicamente 4)
  • Alcune funzionalità dei dispositivi companion potrebbero non essere completamente compatibili con la modalità Coesistenza
  • Il dispositivo companion potrebbe eseguire una versione obsoleta della WhatsApp Business App

Passaggi per la Risoluzione

  1. Controlla la compatibilità del dispositivo: Assicurati che il tuo dispositivo companion soddisfi i requisiti minimi di WhatsApp. Per Android, è richiesta la versione 5.0 o successiva. Per iOS, è richiesta la versione 15.1 o successiva
  2. Aggiorna tutti i dispositivi: Assicurati che sia il telefono principale che il dispositivo companion eseguano l'ultima versione della WhatsApp Business App
  3. Mantieni il dispositivo principale online: Il telefono principale deve rimanere connesso a internet affinché i dispositivi companion funzionino. Se il dispositivo principale va offline per più di 14 giorni, i dispositivi companion verranno disconnessi
  4. Controlla i limiti dei dispositivi companion: WhatsApp consente fino a 4 dispositivi companion. Se hai raggiunto il limite, scollega un dispositivo companion esistente prima di aggiungerne uno nuovo
  5. Ricollega il dispositivo companion: Rimuovi il dispositivo companion dalla WhatsApp Business App (Impostazioni > Dispositivi Collegati) e configuralo nuovamente scansionando il codice QR dal dispositivo principale
  6. Verifica la compatibilità con la Coesistenza: Alcune funzionalità dei dispositivi companion potrebbero avere funzionalità limitate in modalità Coesistenza. Consulta la documentazione di WhatsTeam per le ultime informazioni sulla compatibilità
  7. Testa senza Coesistenza: Disabilita temporaneamente la Coesistenza per determinare se il problema del dispositivo companion è correlato specificamente alla Coesistenza o è un problema generale di connettività WhatsApp

9. Modifiche del Nome Post-Onboarding

Sintomo del Problema

Dopo aver completato il processo di onboarding della WhatsApp Business API, vuoi cambiare il nome visualizzato della tua attività ma la modifica viene rifiutata da Meta, richiede un tempo prolungato per l'elaborazione o non appare sul tuo profilo WhatsApp.

Causa Principale

Le modifiche del nome visualizzato della WhatsApp Business API sono soggette al processo di revisione e approvazione di Meta:

  • Meta applica linee guida rigorose per i nomi visualizzati aziendali
  • Le modifiche del nome richiedono una nuova revisione e approvazione, che può richiedere fino a 72 ore
  • I nomi che violano le politiche di denominazione di Meta verranno rifiutati
  • Modifiche frequenti del nome possono innescare un esame più approfondito o ritardi
  • Il nome visualizzato deve corrispondere al nome aziendale associato al tuo Meta Business Manager

Passaggi per la Risoluzione

  1. Rivedi le linee guida sulla denominazione: Prima di inviare una modifica del nome, rivedi le linee guida sul nome visualizzato di Meta. I nomi devono rappresentare accuratamente la tua attività e non possono includere:
    • Termini generici senza il nome della tua attività
    • Tutte lettere maiuscole (a meno che non sia un acronimo)
    • Nomi fuorvianti o ingannevoli
    • Nomi personali (a meno che l'attività non prenda il nome da una persona)
    • Punteggiatura eccessiva o caratteri speciali
  2. Invia tramite WhatsTeam: Vai alle impostazioni del tuo dispositivo in WhatsTeam e aggiorna il nome visualizzato aziendale. La modifica verrà inviata a Meta per la revisione
  3. Attendi l'approvazione: Le modifiche del nome richiedono tipicamente da 24 a 72 ore per la revisione di Meta. Non inviare più richieste di modifica durante questo periodo, poiché potrebbe ritardare ulteriormente la revisione
  4. Verifica le informazioni aziendali: Assicurati che le informazioni aziendali del tuo Meta Business Manager corrispondano al nome visualizzato che stai richiedendo. Discrepanze tra la registrazione aziendale e il nome visualizzato possono causare rifiuti
  5. Fornisci documentazione di supporto: Se la modifica del nome viene rifiutata, potresti dover fornire documentazione aggiuntiva come certificati di registrazione aziendale, registrazioni di marchi o prove di proprietà del dominio
  6. Usa un nome alternativo: Se il nome preferito continua a essere rifiutato, considera variazioni che rappresentino comunque la tua attività pur rispettando le linee guida di Meta
  7. Contatta il supporto: Se la modifica del nome è in sospeso da più di 72 ore o è stata rifiutata senza una ragione chiara, contatta il supporto WhatsTeam e noi escaleremo la revisione con Meta

Ottenere Assistenza Aggiuntiva

Se continui a riscontrare problemi non coperti da questa guida alla risoluzione dei problemi:

  • Supporto WhatsTeam: Contatta il nostro team di supporto tramite la chat live della piattaforma o email
  • Centro Assistenza Meta Business: Visita il supporto business di Meta per problemi specifici di WhatsApp
  • Documentazione WhatsApp Business API: Consulta la documentazione API ufficiale per dettagli tecnici
  • Forum della Community: Unisciti alla community di WhatsTeam per connetterti con altri utenti che potrebbero aver incontrato problemi simili

Articoli Correlati

Pronto per iniziare?

Prova WhatsTeam gratis