La Guida di Mokapen

WhatsApp Business

L'integrazione WhatsApp Business collega un numero WhatsApp Business della tua organizzazione a Mokapen: puoi inviare e — a differenza dell'SMS — anche ricevere messaggi dai tuoi contatti, gestendo le conversazioni direttamente dalla scheda contatto o dalla casella Messaggi unificata insieme a SMS e chat.

Importante: il canale usa la piattaforma ufficiale WhatsApp Business di Meta. Per collegarlo servono un account Meta Business e un'app Meta Developer con il prodotto WhatsApp configurato (vedi sezione Requisiti): non è un collegamento diretto con l'app WhatsApp che usi sul telefono personale.

Panoramica generale delle integrazioni: Integrazioni.

Requisiti

• Piano Mokapen che include l'integrazione WhatsApp Business (Premium — icona medaglia in pagina se non disponibile per il tuo piano).
• Un portfolio Meta Business verificato.
• Un'app Meta Developer collegata a quel portfolio, con il prodotto WhatsApp configurato.
• Un numero di telefono non già collegato a WhatsApp personale, all'app WhatsApp Business o a un altro provider/servizio API WhatsApp Business. Se il numero è già registrato altrove, va prima migrato alla configurazione di Mokapen seguendo il processo di migrazione di Meta: contatta il supporto Mokapen se hai bisogno di assistenza con la migrazione.
• Credito disponibile nel wallet dell'organizzazione: ogni messaggio inviato scala il credito in base a paese di destinazione e categoria del messaggio (vedi sezione Credito e prezzi).

Collegare l'account WhatsApp Business

Il collegamento avviene con l'Embedded Signup di Meta, cioè una finestra di login Meta/Facebook che ti guida nella scelta del portfolio Business, dell'account WhatsApp Business (WABA) e del numero da collegare — non è un semplice QR code da scansionare.

1. Menu utente → Integrazioni → WhatsApp Business.
2. Premi Connetti WhatsApp Business (serve piano Premium adeguato).
3. Accedi con il tuo account Meta nella finestra che si apre e segui i passaggi guidati: scegli il portfolio Business, l'account WhatsApp Business e il numero di telefono da collegare.
4. Conferma: Mokapen riceve i permessi necessari e sottoscrive automaticamente le notifiche (webhook) per quell'account.

Se durante il collegamento Meta segnala che il numero è già su un altro provider API WhatsApp Business, scegli l'opzione di migrazione proposta e confermi che il numero è già su WhatsApp Business API; se invece il numero è ancora sull'app WhatsApp personale, va prima eliminato l'account su quel telefono e va atteso circa 15 minuti prima di riprovare. Se il numero ha la verifica in due passaggi attiva, va disabilitata prima della connessione (in WhatsApp Manager o tramite il provider attuale).

Attivare il numero

Dopo l'Embedded Signup, il numero va attivato prima di poter inviare messaggi:

1. Nella pagina Integrazioni → WhatsApp Business premi Attiva numero.
2. Se richiesto, richiedi un codice di verifica via SMS o chiamata vocale al numero collegato e inseriscilo quando arriva.
3. Inserisci un PIN a 6 cifre: se la verifica in due passaggi esiste già su quel numero, usa il PIN esistente; altrimenti questo diventa il nuovo PIN richiesto in futuro da Meta per operazioni sul numero.
4. Opzionale: scegli una regione di localizzazione dei dati. Una volta abilitata, può essere modificata solo deregistrando e registrando di nuovo il numero.
5. Conferma: se tutto è corretto il numero passa allo stato attivo e puoi iniziare a usare l'integrazione.

Meta consente massimo 10 richieste di registrazione per lo stesso numero di telefono in una finestra di 72 ore: se superi il limite, attendi prima di riprovare. Se il PIN non è corretto, controllalo in WhatsApp Manager o reimpostalo con il provider precedente se hai appena migrato il numero.

Credito e prezzi

L'invio di messaggi WhatsApp è a consumo: usa lo stesso wallet (credito prepagato) dell'organizzazione impiegato da altre funzionalità a consumo di Mokapen, come l'SMS — non è un credito separato.

• Il costo per messaggio dipende dal paese di destinazione del numero e dalla categoria del messaggio (marketing, utility, authentication, o messaggio libero di conversazione entro la finestra delle 24 ore — vedi sezioni successive).
• In pagina Integrazioni → WhatsApp Business vedi sempre il Credito disponibile dell'organizzazione, con link diretto alla ricarica del wallet.
• Il credito viene scalato al momento dell'invio, non prima.
• Se il credito non basta, l'invio è bloccato e Mokapen mostra un avviso — "Crediti WhatsApp Business insufficienti. Ricarica i crediti per inviare messaggi." — con collegamento diretto alla pagina di ricarica.

La ricarica del wallet è visibile a Proprietario e membri con permesso sull'organizzazione; verifica il saldo prima di campagne o invii massivi di modelli marketing.

Inviare un messaggio manualmente

Il pulsante di invio WhatsApp è disponibile sulla scheda contatto. Premendo l'icona WhatsApp:

1. Seleziona il numero di telefono del contatto a cui scrivere (tra quelli presenti sulla scheda).
2. Se hai più account WhatsApp Business collegati, scegli quale usare.
3. Se sei dentro la finestra delle 24 ore (il contatto ti ha scritto di recente, vedi sezione successiva), puoi scrivere un messaggio libero come su WhatsApp normale. Se sei fuori finestra o è il primo contatto, devi scegliere un modello approvato da Meta: solo i modelli con stato Approvato sono selezionabili nel menu.
4. Se il modello ha segnaposto ({{1}}, {{2}}…), compila i valori richiesti prima di procedere: senza i valori il modello resta disabilitato.
5. Controlla l'anteprima del messaggio (mostrata come un fumetto WhatsApp) e premi Invia. In caso di successo compare la conferma "Messaggio WhatsApp Business inviato con successo." e il messaggio entra nello storico del contatto.

Se non hai ancora un'integrazione WhatsApp Business attiva, il pulsante ti reindirizza alla pagina Integrazioni → WhatsApp Business per completare prima il collegamento.

La finestra delle 24 ore

WhatsApp Business impone una regola valida per tutte le aziende sulla piattaforma, non solo per Mokapen: puoi scrivere testo libero (senza modello) a un contatto solo entro 24 ore dall'ultimo messaggio che quel contatto ti ha inviato — la cosiddetta finestra di assistenza clienti.

• Se il contatto ti scrive, la finestra si apre (o si rinnova) e per 24 ore puoi rispondere liberamente con testo o allegati.
• Trascorse le 24 ore senza un nuovo messaggio in arrivo, oppure se non hai mai ricevuto un messaggio da quel numero, per scrivergli devi usare un modello approvato da Meta (vedi sezione successiva): è così che si avvia o si riprende una conversazione commerciale al di fuori della finestra.
• Se provi a inviare testo libero fuori finestra, l'invio viene bloccato: scegli un modello adatto (tipicamente categoria Utility) invece del messaggio libero.

Modelli WhatsApp Business

I modelli di messaggio (template) sono formati preapprovati da Meta, necessari per avviare una conversazione o scrivere fuori dalla finestra delle 24 ore. Puoi gestirli in due modi:

• Sincronizzare modelli già esistenti su Meta — dalla pagina Integrazioni → WhatsApp Business, usa Sincronizza modelli: Mokapen importa i modelli con stato Approvato non ancora collegati, così puoi usarli subito nell'invio manuale.
• Creare o modificare modelli in Mokapen — in Impostazioni → Modelli, tipo WhatsApp Business: la creazione, modifica o eliminazione avviene direttamente su Meta tramite l'app collegata, e lo stato di approvazione si aggiorna automaticamente quando Meta lo comunica.

Alcune regole importanti quando crei un modello:

• Categoria — Utility (aggiornamenti transazionali attesi dall'utente: stato ordine, promemoria appuntamenti, avvisi account), Marketing (promozioni, offerte, newsletter: richiede che il destinatario abbia dato un consenso esplicito a ricevere messaggi WhatsApp dalla tua azienda) o Authentication (codici OTP o di verifica, con pulsanti dedicati). La categoria deve corrispondere al contenuto reale: una categorizzazione errata può portare al rifiuto o a un punteggio di qualità più basso.
• Struttura — intestazione opzionale (testo, immagine, video, documento o posizione), corpo obbligatorio, piè di pagina opzionale, fino a 3 pulsanti (risposta rapida, link URL o numero di telefono).
• Nome — solo lettere minuscole, numeri e underscore (es. conferma_ordine), univoco per account e lingua.
• Segnaposto — usa {{1}}, {{2}}, {{3}} in ordine e senza salti; fornisci valori di esempio in fase di creazione.
• Limiti di caratteri — corpo massimo 1.024 caratteri, intestazione testuale e piè di pagina massimo 60 caratteri ciascuno, etichetta pulsante massimo 20 caratteri, massimo 3 pulsanti per modello.

Ogni modello viene esaminato da Meta prima dell'uso: l'approvazione richiede in genere pochi minuti, a volte fino a 24 ore. Un modello rifiutato mostra il motivo del rifiuto; un punteggio di qualità basso o troppi blocchi/segnalazioni da parte dei destinatari possono limitare l'account WhatsApp Business.

Storico, conversazioni e ricezione

A differenza dell'SMS, WhatsApp Business è bidirezionale: un contatto può scriverti liberamente e il messaggio arriva davvero come nuova conversazione in Mokapen.

• Scheda del contatto — nello storico/timeline compaiono sia i messaggi inviati che quelli ricevuti, con anteprima del testo.
• Casella Messaggi — i thread WhatsApp compaiono insieme a SMS e chat nella stessa casella unificata, con ricerca sul testo. A differenza dell'SMS, per WhatsApp Mokapen aggiorna automaticamente lo stato di consegna e lettura (inviato, consegnato, letto) man mano che Meta notifica gli eventi.
• Un contatto può inviarti testo, immagini, documenti, audio, video e sticker, anche in risposta a un messaggio specifico: tutto arriva nello stesso thread nella casella Messaggi.

Limiti da conoscere

• Non disponibile nelle automazioni — a oggi il modulo Automazioni offre le azioni Invia Email e Invia SMS, ma non un'azione per WhatsApp Business: l'invio è possibile solo manualmente dalla scheda contatto.
• Testo libero solo entro 24 ore — fuori dalla finestra di assistenza clienti serve sempre un modello approvato da Meta.
• Un solo canale sul contatto oggi — il pulsante di invio è disponibile su Contatti; per Aziende o altre schede l'invio WhatsApp non è ancora esposto in interfaccia.
• Numero non condivisibile con altri usi — un numero collegato a Mokapen tramite WhatsApp Business API non può restare contemporaneamente attivo sull'app WhatsApp personale o su un altro provider API.
• Limite di registrazione — massimo 10 tentativi di attivazione per numero ogni 72 ore imposto da Meta, non da Mokapen.

Problemi comuni

• Impossibile completare la connessione — verifica di avere un portfolio Meta Business verificato, un'app Developer collegata con il prodotto WhatsApp configurato, e riprova l'Embedded Signup.
• Numero ancora sull'app WhatsApp personale — elimina l'account WhatsApp per quel numero sul telefono, attendi circa 15 minuti e riprova la connessione.
• Numero già su un altro provider API — durante la connessione scegli l'opzione di migrazione e confermalo; se la verifica in due passaggi è attiva su quel numero, disabilitala prima in WhatsApp Manager o tramite il provider attuale.
• PIN di verifica errato — controlla il PIN a 6 cifre della verifica in due passaggi in WhatsApp Manager, o reimpostalo con il provider precedente se hai appena migrato.
• WhatsApp è connesso ma la sottoscrizione del webhook non è riuscita — i messaggi in arrivo potrebbero non comparire: contatta il supporto Mokapen se il problema persiste dopo aver riprovato la connessione.
• Il messaggio libero non parte — probabilmente sei fuori dalla finestra delle 24 ore: scegli un modello approvato invece del testo libero.
• Modello rifiutato da Meta — controlla il motivo del rifiuto indicato: categoria non corrispondente al contenuto, segnaposto non numerati correttamente, contenuti non ammessi (spam, urgenza falsa, dati sensibili) o formato non conforme.
• Crediti insufficienti — ricarica il wallet dell'organizzazione dal link in pagina Integrazioni → WhatsApp Business o dalla sezione Fatturazione.

Disconnettere

Dalla pagina Integrazioni → WhatsApp Business premi Disconnetti: si apre una finestra con la sezione Mantieni.

• La casella Messaggi & Modelli è spuntata di default: lasciandola spuntata, storico messaggi e modelli sincronizzati restano visibili in Mokapen anche dopo la disconnessione.
• Se la deselezioni, Mokapen elimina i modelli sincronizzati, i thread e i messaggi WhatsApp legati a questa integrazione, oltre ai relativi file multimediali.

In ogni caso vengono sempre rimossi il collegamento con l'account Meta e la sottoscrizione del webhook. Se sei un utente con cui l'integrazione è stata condivisa (non il proprietario), la disconnessione rimuove solo il tuo accesso: l'integrazione resta attiva per l'organizzazione. Per confermare, digita DISCONNETTI nel campo richiesto.

Casi d'uso

• Conferma ordine o appuntamento — usi un modello Utility approvato per confermare un ordine appena chiuso o un appuntamento fissato: il cliente riceve la notifica anche se non ti ha ancora scritto, senza dover aspettare che apra un'email.
• Assistenza clienti in tempo reale — un cliente ti scrive su WhatsApp per una domanda: il messaggio arriva nella scheda contatto e nella casella Messaggi, e per le successive 24 ore puoi rispondere con testo libero, immagini o documenti senza dover passare da un modello.
• Aggiornamento stato spedizione — modello Utility con segnaposto per numero d'ordine e data prevista, inviato manualmente dalla scheda contatto quando lo stato della spedizione cambia.
• Codice di verifica — modello categoria Authentication con pulsante OTP dedicato, utile quando serve inviare un codice di sicurezza a un contatto in modo affidabile e tracciato nello storico.
• Campagna con consenso esplicito — modello Marketing inviato ai soli contatti che hanno dato consenso esplicito a ricevere messaggi WhatsApp dall'azienda, ad esempio per annunciare una promozione stagionale.

Domande frequenti

D: Posso ricevere messaggi dai miei clienti in Mokapen, a differenza dell'SMS?

A: Sì. WhatsApp Business è bidirezionale: se un contatto ti scrive, il messaggio appare come nuova conversazione nella scheda contatto e nella casella Messaggi, ed entro 24 ore puoi rispondere con testo libero.

D: Serve davvero un account Meta Business per collegare WhatsApp?

A: Sì. Servono un portfolio Meta Business verificato e un'app Meta Developer con il prodotto WhatsApp configurato: il collegamento avviene tramite l'Embedded Signup di Meta, non con un login diretto sull'app WhatsApp del telefono.

D: Il mio numero è già su WhatsApp normale o su un altro provider: posso comunque collegarlo?

A: Sì, ma va prima liberato o migrato: se è sull'app WhatsApp personale, elimina l'account su quel telefono e attendi circa 15 minuti; se è già su un altro provider API WhatsApp Business, scegli l'opzione di migrazione durante la connessione e conferma.

D: Posso scrivere liberamente a un cliente in qualsiasi momento?

A: No. Puoi scrivere testo libero solo entro 24 ore dall'ultimo messaggio che il cliente ti ha inviato. Fuori da questa finestra, o per il primo contatto, devi usare un modello approvato da Meta.

D: Come creo o aggiorno un modello di messaggio?

A: In Impostazioni → Modelli, tipo WhatsApp Business: crei o modifichi il modello, che viene salvato e sottoposto ad approvazione direttamente su Meta. In alternativa, se hai già modelli approvati su Meta, usa Sincronizza modelli dalla pagina Integrazioni → WhatsApp Business per importarli.

D: Quanto costa inviare un messaggio WhatsApp?

A: Il costo dipende dal paese di destinazione e dalla categoria del messaggio (marketing, utility, authentication o conversazione libera nella finestra delle 24 ore). Il credito viene scalato dal wallet dell'organizzazione al momento dell'invio: verifica il saldo disponibile nella pagina Integrazioni → WhatsApp Business.

D: WhatsApp Business è disponibile come azione nelle automazioni, come Email o SMS?

A: No, non ancora: oggi il modulo Automazioni offre solo Invia Email e Invia SMS. L'invio di messaggi WhatsApp è possibile esclusivamente in modo manuale dalla scheda contatto.

D: Perché un mio modello è stato rifiutato da Meta?

A: I motivi più comuni sono: categoria che non corrisponde al contenuto reale del messaggio, segnaposto numerati in modo scorretto o con salti, contenuti non ammessi (spam, urgenza falsa, richieste di dati sensibili) o formato non conforme alle regole di struttura. Il motivo esatto del rifiuto è indicato da Meta sul modello.

D: Cosa succede ai dati se disconnetto l'integrazione?

A: Con la casella «Messaggi & Modelli» spuntata (impostazione predefinita), storico messaggi e modelli sincronizzati restano visibili in Mokapen. Deselezionandola, Mokapen elimina modelli, thread, messaggi e file multimediali legati a quella integrazione. Il collegamento con l'account Meta viene comunque sempre rimosso.

D: Posso usare più numeri WhatsApp Business nella stessa organizzazione?

A: Sì, se il tuo account WhatsApp Business (WABA) ha più numeri collegati o se colleghi più account: nel compositore, se disponibili più opzioni, scegli quale usare come mittente prima di inviare.