WhatsApp Business API: Errori Comuni e Risoluzione dei Problemi

Questa guida fornisce soluzioni per gli errori più frequenti di integrazione, template e messaggistica riscontrati quando si utilizza la WhatsApp Business API con WhatsTeam.

Errori di Integrazione e Configurazione

Questo numero è registrato su un account WhatsApp esistente

Questo errore si verifica se il tuo numero di telefono è già collegato a un altro provider di WhatsApp Business API o all'app mobile WhatsApp/WhatsApp Business standard.

• Se usi un altro provider API: Segui la nostra guida alla migrazione per trasferire il tuo numero a WhatsTeam.
• Se usi l'app mobile: Devi disconnettere formalmente il numero dall'app prima che possa essere utilizzato con la Cloud API. Nota che questo cancellerà la cronologia delle chat locali a meno che tu non abbia un backup.
• Ancora bloccato? Contatta il nostro team di supporto a support@whats.team con il tuo WhatsApp Business Account ID e il numero di telefono per assistenza manuale.

Impossibile inviare il codice o errore 500 nella console

Se non ricevi un codice di verifica o vedi un "500 Internal Server Error" durante la registrazione:

1. Controlla la console: Esamina la console sviluppatori del tuo browser. Spesso si tratta di errori di validazione da Meta riguardanti le impostazioni del profilo aziendale (es. descrizione troppo lunga).
2. Prova il flusso per la prima volta: Se stavi tentando una migrazione, prova il percorso "Configurazione iniziale", poiché l'account potrebbe essere già stato parzialmente creato.
3. Attendi e riprova: I server di Meta a volte subiscono ritardi temporanei. Attendi 5-10 minuti prima di richiedere un nuovo codice.

Accesso al WhatsApp Business Account non condiviso

Questo si verifica quando la connessione tra il tuo Meta Business Account e WhatsTeam non è stata completamente autorizzata o i permessi sono stati revocati.

• Risoluzione: Riesegui il processo di embedded signup e assicurati che tutte le caselle di controllo per i permessi siano selezionate.

Richiesta get non supportata o ID non valido

Errore: "L'oggetto con ID XXX non esiste..." Questo accade generalmente quando viene inserito un Business Manager ID invece di un WhatsApp Business Account (WABA) ID. Ricontrolla di stare usando il WABA ID che si trova nelle Impostazioni Business di Meta sotto 'Account WhatsApp'.

Impossibile migrare il numero di telefono

Errore: "Impossibile migrare il numero di telefono. L'account WhatsApp a cui è registrato questo numero non è configurato correttamente."

1. Verifica che il numero sia completamente approvato nella tua Meta Business Suite.
2. Assicurati che il numero non sia più attivo su alcun dispositivo mobile.
3. Fai uno screenshot del numero verificato nella tua dashboard Meta e invialo al nostro team di supporto se il problema persiste.

Impossibile creare il certificato (Conflitto 2FA)

WhatsApp non può generare un certificato di sicurezza se l'autenticazione a due fattori (2FA) è abilitata sul numero di telefono nell'app mobile. Disabilita la 2FA nelle impostazioni dell'app WhatsApp prima di tentare la connessione a WhatsTeam.

Assicurati di autorizzare completamente l'accesso

Questo messaggio appare tipicamente se c'è un ritardo di sincronizzazione tra l'approvazione di Meta e la nostra piattaforma.

• Risoluzione: Aggiorna il browser e attendi 2-5 minuti affinché i permessi si propaghino tra i sistemi.

WABA già utilizza un metodo di pagamento

Questo accade quando un numero era precedentemente fornito da un provider di terze parti che ha associato il proprio metodo di pagamento. Devi completare il processo di migrazione per spostare il numero sotto il tuo Meta Business Account e la tua struttura di pagamento.

Problemi con i Modelli di Messaggio

I template non appaiono nella dashboard

Se i tuoi template Meta approvati non vengono visualizzati in WhatsTeam:

• Solo Testo Semplice: Assicurati che il template non utilizzi tipi di media non supportati o elementi interattivi complessi non ancora supportati nella vista corrente.
• Corrispondenza Lingua: Verifica che la lingua del template corrisponda alle impostazioni di lingua del tuo account.
• Stato Sincronizzazione: L'approvazione di Meta può richiedere fino a 24 ore. Se è già approvato in Meta, prova ad aggiornare la connessione nella dashboard.

Formattazione delle variabili (placeholder numerici)

La WhatsApp Cloud API richiede placeholder numerici (es. {{1}}, {{2}}) nel corpo del template.

• Errato: Ciao {{nome}}, il tuo ordine {{id_ordine}} è pronto.
• Corretto: Ciao {{1}}, il tuo ordine {{2}} è pronto. Puoi quindi mappare queste variabili numeriche agli attributi utente all'interno di WhatsTeam quando invii il messaggio.

Prevenire la riclassificazione a "Marketing"

Meta può riclassificare automaticamente i template "Utilità" o "Servizio" come "Marketing" se contengono linguaggio promozionale.

• Suggerimento: Mantieni un linguaggio neutro, evita le emoji negli aggiornamenti transazionali e sii molto specifico sullo scopo del servizio quando invii per l'approvazione.

Problemi di Consegna dei Messaggi

Messaggio non consegnabile / Destinatario non raggiungibile

Questo di solito significa che l'account WhatsApp del destinatario non può ricevere il messaggio.

• Cause: Il numero non è su WhatsApp, l'utente non ha accettato i Termini di Servizio più recenti, o sta usando una versione estremamente obsoleta dell'app.
• Soluzione: Chiedi all'utente (tramite SMS o email) di inviarti prima un messaggio per "scaldare" la conversazione e assicurarti che la sua app sia aggiornata.

Limiti di frequenza dei messaggi

Se un messaggio fallisce a causa dei "limiti di frequenza", Meta ha limitato il numero di template marketing che questo specifico utente può ricevere in un breve periodo per prevenire lo spam.

• Azione: Attendi 24 ore prima di tentare un nuovo invio. Consulta la documentazione di Meta per maggiori dettagli.

La finestra di conversazione di 24 ore

WhatsApp applica una finestra di servizio di 24 ore. Puoi inviare messaggi a formato libero solo se l'utente ha risposto nelle ultime 24 ore.

• Se la finestra è chiusa: Devi inviare un Messaggio Template pre-approvato per ricontattare l'utente. Una volta che risponde, la finestra di 24 ore per la chat a formato libero si riapre.

Tipo di media non supportato

Se un'immagine o un documento non riesce a essere inviato:

• Verifica che la dimensione del file sia entro i limiti di Meta.
• Assicurati che il formato del file (es. .jpg, .pdf, .mp4) sia supportato dalla piattaforma WhatsApp.

Il destinatario fa parte di un esperimento WhatsApp

Occasionalmente, Meta conduce esperimenti in cui determinati messaggi marketing non possono essere consegnati a utenti specifici. Se vedi un errore che menziona un "esperimento", prova a inviare un tipo di messaggio diverso o a reinviare più tardi.

Account limitato o bloccato

Se ricevi un errore che indica che l'"Account è bloccato", il tuo WABA potrebbe essere stato sospeso per violazioni delle policy.

• Risoluzione: Controlla la tua Casella di Supporto di Meta Business Suite per eventuali notifiche riguardanti l'applicazione delle policy e segui le istruzioni per presentare ricorso o risolvere la restrizione.

Hai Ancora Problemi?

Se il tuo problema non è trattato qui, il nostro team di supporto è pronto ad aiutarti. Contattaci a support@whats.team.