💬 Configurazione WhatsApp Business API
Guida completa per integrare WhatsApp Business con AI4CALL: invia messaggi automatici ai clienti tramite template approvati Meta durante o dopo le chiamate
Vai in "MARKET" → "Marketplace Plugin" e clicca su Acquista di "WhatsApp" → FREE
Vai in "MARKET" → "I Miei Plugin" e clicca su Configura di "WhatsApp"
🚀 Navigazione rapida:
⚠️ Servizi di terze parti
Le integrazioni descritte fanno riferimento a servizi di terze parti.
Rate limit, modalità di autenticazione, configurazioni tecniche, costi e policy sono definiti esclusivamente dai rispettivi provider e possono variare nel tempo.
I costi dei servizi esterni sono sostenuti direttamente dall’utente finale a favore dei fornitori dei servizi stessi e non sono in alcun modo gestiti o intermediati dal nostro portale (es. Meta o altri fornitori per WhatsApp, Zapier, Calendly, ecc.).
Puoi inviare SOLO messaggi basati su template pre-approvati da Meta:
- ❌ NON puoi scrivere messaggi WhatsApp liberi come nell'app normale
- ❌ NON puoi generare testo dinamico completamente libero
- ✅ DEVI creare template in Meta Business Manager
- ✅ DEVI attendere approvazione Meta (24-48 ore)
- ✅ PUOI personalizzare template con parametri dinamici (nome, data, etc.)
Eccezione: se il cliente ti scrive per primo, puoi rispondere liberamente entro 24h (session message). Ma AI4CALL invia messaggi proattivamente - quindi servono template approvati.
Cos'è WhatsApp Business API e come funziona
WhatsApp Business API è una piattaforma enterprise di Meta (Facebook) per inviare messaggi WhatsApp automatici e programmabili a clienti su larga scala.
- 📱 interfaccia app mobile/desktop
- 💬 chat manuali persona-a-persona
- 🆓 completamente gratuito
- 👤 uso personale o piccole aziende
- ✍️ scrivi messaggi liberi come vuoi
WhatsApp Business API (piattaforma):
- 🔌 nessuna interfaccia - solo API programmabile
- 🤖 messaggi automatici da software/AI
- 💰 a pagamento per conversazione (~€0.005-0.05)
- 🏢 enterprise - richiede verifica business Meta
- 📝 SOLO template pre-approvati da Meta
[Cliente chiama AI4CALL]
↓
[Assistente AI gestisce chiamata]
↓
[Raccoglie: nome, numero WhatsApp, dati rilevanti]
↓
[Fine chiamata]
↓
[Assistente invoca send_whatsapp_message]
↓
[Seleziona template approvato: es. "appointment_confirmation"]
↓
[Compila parametri template: {{nome}}, {{data}}, {{ora}}]
↓
[POST a WhatsApp Business API con credenziali Meta]
↓
[Meta valida template + parametri]
↓
[Meta invia messaggio WhatsApp al cliente]
↓
[Cliente riceve notifica WhatsApp su smartphone]
Vantaggio: cliente riceve conferma immediata su app che già usa quotidianamente (98% read rate vs 20% email).
Pricing per paese (esempi Italia):
- Service-initiated (azienda contatta cliente prima): ~€0.0286 per conversazione
- User-initiated (cliente contatta azienda prima): ~€0.0048 per conversazione
- Authentication (OTP, 2FA): ~€0.0270 per conversazione
Free tier: prime 1.000 conversazioni/mese GRATIS
Conversazione: finestra 24h - puoi inviare messaggi multipli nello stesso periodo senza costi aggiuntivi
AI4CALL non aggiunge costi - paghi SOLO a Meta. Fatturazione Meta su carta credito business.
Verifica prezzi aggiornati: WhatsApp Pricing
Setup Meta Business Manager e credenziali API
Per usare WhatsApp Business API devi creare e verificare un account Meta Business Manager e ottenere le credenziali necessarie.
- Vai su business.facebook.com
- Clicca "Crea account" → inserisci nome business, tuo nome, email aziendale
- Conferma email e completa setup iniziale
FASE 2 - Verifica business (obbligatorio per produzione):
- Meta Business Manager → Impostazioni → Informazioni Business
- Clicca "Verifica la tua attività"
- Fornisci: nome legale azienda, indirizzo, P.IVA/codice fiscale, documento ufficiale
- Attendi review Meta: 1-3 giorni lavorativi
- Status: verificato ✅ o rifiutato ❌ (se rifiutato, correggi e risubmit)
FASE 3 - Aggiungi WhatsApp al Business Manager:
- Meta Business Manager → menu ☰ → WhatsApp
- Clicca "Get Started" o "Inizia"
- Segui wizard: seleziona "Use WhatsApp Business API"
- Accetta termini di servizio WhatsApp Business
FASE 4 - Aggiungi numero telefono WhatsApp:
- WhatsApp Manager → Phone Numbers → Add Phone Number
- Inserisci numero telefono dedicato (NON può essere usato su app WhatsApp normale!)
- Scegli metodo verifica: SMS o chiamata vocale
- Inserisci codice verifica ricevuto
- ✅ Numero verificato e registrato su WhatsApp Business API
- Copia e salva "Phone Number ID" - ti servirà per AI4CALL
FASE 5 - Genera Access Token permanente:
- Meta Business Manager → Impostazioni → Utenti → Utenti di sistema
- Clicca "Aggiungi" → nome: "AI4CALL API User"
- Clicca sull'utente creato → "Genera nuovo token"
- Seleziona app WhatsApp dalla lista
- Permessi: seleziona
whatsapp_business_messagingewhatsapp_business_management - Scadenza: seleziona "Never" (mai) per token permanente
- Genera token → COPIA IMMEDIATAMENTE (inizia con EAAG... lungo ~200 caratteri)
- ⚠️ Token non sarà più visibile - salvalo in password manager sicuro!
- ✅ Access Token: stringa lunga inizia con
EAAG... - ✅ Phone Number ID: numero a 15 cifre (es.
123456789012345) - ✅ Numero WhatsApp: verificato e dedicato all'API
- ✅ Business verificato: badge ✅ in Meta Business Manager
Conserva Access Token e Phone Number ID - li userai nella configurazione AI4CALL!
Protezione:
- 🔒 NON condividere token con terzi non autorizzati
- 🔒 NON committare token in repository Git pubblici
- 🔒 conserva in password manager aziendale sicuro
- 🔒 usa token permanente solo per produzione - token temporanei per test
- 🔒 rigenera token se sospetti compromissione
Se token compromesso: Meta Business Manager → Utenti di sistema → elimina utente → ricrea con nuovo token.
Crea e approva template messaggi WhatsApp
Prima di poter inviare messaggi, devi creare template e farli approvare da Meta (24-48 ore).
- Meta Business Manager → WhatsApp → Message Templates
- Clicca "Create Template"
- Categoria template: scegli tipo
- Utility: conferme, aggiornamenti account, transazioni (es. conferma appuntamento)
- Marketing: promozioni, offerte, newsletter
- Authentication: OTP, codici verifica 2FA
- Nome template: identificativo univoco
→ es.appointment_confirmation,order_summary
→ solo minuscole, numeri, underscore (no spazi, caratteri speciali) - Lingua: seleziona lingua template (es. Italian)
- Header (opzionale):
- Text: testo fisso o con variabile {{1}}
- Image: upload immagine o fornisci URL (max 5MB)
- Video: upload video (max 16MB)
- Document: PDF/doc (max 100MB)
- Body (obbligatorio): testo principale messaggio
→ usa placeholders dinamici:{{1}},{{2}},{{3}}
→ formattazione:*grassetto*,_corsivo_,~barrato~
→ max 1.024 caratteri
Esempio body:Gentile *{{1}}*, confermiamo appuntamento per {{2}} alle ore {{3}}. Grazie! - Footer (opzionale): testo piccolo fondo messaggio
→ es.Powered by AI4CALL,Non rispondere a questo messaggio - Buttons (opzionale): fino a 3 button
- Call to Action: apre URL o chiama numero
- Quick Reply: risposta rapida (testo predefinito)
- Preview: verifica anteprima messaggio
- Clicca "Submit" per inviare a review Meta
- Attendi 24-48h per approvazione
Nome:
appointment_confirmation Categoria: Utility
Body:
Gentile *{{1}}*,
Confermiamo il suo appuntamento:
📅 Data: {{2}}
🕐 Ora: {{3}}
📍 Luogo: {{4}}
Ci vediamo presto!
Template 2 - Riepilogo chiamata:
Nome:
call_summary Categoria: Utility
Body:
Ciao {{1}},
Grazie per aver chiamato! 📞
_Riepilogo:_
{{2}}
Per assistenza: supporto@azienda.com
Template 3 - Promemoria:
Nome:
reminder_24h Categoria: Utility
Body:
⏰ *Promemoria*
{{1}}, le ricordiamo appuntamento di domani {{2}} alle {{3}}.
Conferma presenza rispondendo a questo messaggio.
- ❌ contengono spam, contenuti vietati, informazioni fuorvianti
- ❌ chiedono informazioni sensibili (password, dati carta credito)
- ❌ categoria sbagliata (es. marketing camuffato da utility)
- ❌ grammatica/spelling scorretti
- ❌ troppo generici o ambigui
- ❌ violano privacy o copyright
Best practice:
- ✅ sii specifico e chiaro sullo scopo messaggio
- ✅ usa categoria corretta
- ✅ evita termini spam ("GRATIS!!!", "CLICCA ORA")
- ✅ rispetta privacy - no richiesta dati sensibili
- ✅ fornisci valore reale al destinatario
Se rifiutato: modifica template secondo feedback Meta e risubmit.
Configura WhatsApp in AI4CALL
Inserisci le credenziali Meta Business Manager in AI4CALL per abilitare l'invio messaggi WhatsApp.
→ token lungo inizia con
EAAG... → copiato da Meta Business Manager → System Users → Generate Token
→ permessi:
whatsapp_business_messaging Phone Number ID:
→ numero a 15 cifre identificativo numero WhatsApp Business
→ copiato da WhatsApp Manager → Phone Numbers → ID numero
→ es.
123456789012345 Template Name:
→ nome template approvato da Meta che vuoi usare
→ es.
appointment_confirmation, call_summary → deve avere status Approved in Meta Business Manager
- Verifica che tutti i campi siano corretti
- Access Token valido e non scaduto
- Phone Number ID corretto (15 cifre)
- Template Name esiste e status=Approved
Test: fai chiamata di prova e chiedi all'assistente di inviare WhatsApp al tuo numero. Dovresti ricevere messaggio basato su template configurato!
1. Access Token:
- → token copiato completamente (lunghissimo ~200 caratteri)
- → permessi corretti: whatsapp_business_messaging
- → token non scaduto (se temporaneo)
2. Phone Number ID:
- → 15 cifre esatte
- → corrisponde al numero WhatsApp Business registrato
3. Template:
- → nome esatto (case-sensitive)
- → status = Approved (non Pending/Rejected)
- → lingua template match lingua messaggio
Istruisci l'assistente per workflow WhatsApp
Configura il prompt dell'assistente per utilizzare correttamente send_whatsapp_message con template approvati.
"Al termine della prenotazione, invia conferma WhatsApp usando template 'appointment_confirmation'. Parametri: {{1}}=nome cliente, {{2}}=data appuntamento, {{3}}=ora, {{4}}=indirizzo location. Numero destinatario: numero chiamante."
2. Riepilogo chiamata conciso:
"Se chiamata >3 minuti con informazioni importanti, chiedi: 'Vuole riepilogo WhatsApp?'. Se sì, usa template 'call_summary'. Parametri: {{1}}=nome, {{2}}=riepilogo UNA FRASE (max 150 caratteri) tipo 'Appuntamento fissato 15 marzo ore 10' o 'Richiesta preventivo inviata via email'."
3. Fallback multi-channel:
"Priorità notifica: 1.WhatsApp (se numero valido), 2.Email (fallback se WhatsApp fallisce), 3.SMS (ultimo resort). Prova in ordine fino a successo. Non informare cliente dei fallback - semplicemente usa metodo successivo."
4. Gestione errori gracefully:
"Se send_whatsapp_message fallisce (numero non WhatsApp, template non approvato, errore API), NON dire al cliente 'errore tecnico'. Invece usa fallback silenzioso: prova Email. Solo se TUTTO fallisce, informa: 'le invierò conferma appena possibile via SMS'."
- Chiama assistente AI4CALL dal tuo numero WhatsApp
- Simula prenotazione appuntamento: fornisci nome, data, ora
- L'assistente dovrebbe invocare send_whatsapp_message al termine
- Verifica ricezione messaggio WhatsApp su tuo smartphone
- Controlla: template corretto, parametri compilati, formattazione OK
Test fallback:
- Chiama da numero NON WhatsApp (es. numero fisso)
- L'assistente dovrebbe fallire WhatsApp e usare Email automaticamente
- Verifica non comunichi errore al cliente - solo "le invio conferma via email"
🛠️ Tool send_whatsapp_message
Specifiche tecniche del tool MCP per invio messaggi WhatsApp Business tramite template.
send_whatsapp_message
Parametri:
to(obbligatorio, string): numero destinatario formato internazionale (es. +393331234567)template_name(obbligatorio, string): nome template approvato Metaparameters(opzionale, array): valori per placeholders template [{{1}}, {{2}}, ...]language_code(opzionale, string): codice lingua template (default: "it" per italiano)
Esempio 1 - Conferma appuntamento:
send_whatsapp_message({
to: "+393331234567",
template_name: "appointment_confirmation",
parameters: ["Mario Rossi", "15 marzo 2025", "10:00", "Via Roma 1, Milano"]
})
Esempio 2 - Riepilogo chiamata:
send_whatsapp_message({
to: "+393331234567",
template_name: "call_summary",
parameters: ["Mario", "Preventivo €500 inviato, risposta entro 3 giorni"]
})
Response attesa:
- ✅ Success:
{"status": "sent", "message_id": "wamid.xxx..."} - ❌ Error:
{"error": "template not found"}→ template non approvato - ❌ Error:
{"error": "invalid phone number"}→ numero non WhatsApp
❓ Domande Frequenti
Risposte alle domande più comuni su WhatsApp Business API
WhatsApp normale: app per comunicazioni personali/piccole aziende, gratuita, interfaccia mobile/desktop. WhatsApp Business API: piattaforma enterprise per automazione, richiede approvazione Meta, integrazione programmabile, costi per conversazione, NO interfaccia app (solo API). AI4CALL usa Business API per inviare messaggi automatici durante chiamate - non puoi usare WhatsApp normale.
NO. WhatsApp Business API richiede template pre-approvati da Meta per messaggi service-initiated (azienda → cliente). Template devono essere creati in Meta Business Manager, sottoposti a review, approvati (24-48h). Solo dopo approvazione puoi usarli. Questo previene spam. Eccezione: se cliente ha scritto negli ultimi 24h, puoi rispondere liberamente (session message).
Procedura: (1) Meta Business Manager → WhatsApp → Message Templates → Create Template, (2) scegli categoria (Utility, Marketing, Authentication), (3) scrivi testo con placeholders {{1}}, {{2}}, (4) aggiungi header/footer/button opzionali, (5) Submit for Review. Meta review in 24-48h. Se approvato: status=Approved, utilizzabile. Se rifiutato: modifica e risubmit. Template deve rispettare policy Meta (no spam, no contenuti vietati).
Template WhatsApp contiene placeholders dinamici: {{1}}, {{2}}, {{3}} etc. Esempio template "appointment_reminder": "Gentile {{1}}, appuntamento confermato per {{2}} alle ore {{3}}". Quando invii messaggio, fornisci array parametri: ["Mario Rossi", "15 marzo", "10:00"]. WhatsApp sostituisce: "Gentile Mario Rossi, appuntamento confermato per 15 marzo alle ore 10:00". Ordine parametri deve matchare ordine placeholders.
Procedura: (1) crea account Meta Business Manager su business.facebook.com, (2) completa verifica business, (3) vai a WhatsApp → Getting Started, (4) aggiungi numero telefono business (verifica con SMS), (5) copia Phone Number ID dalla dashboard, (6) vai a System Users → crea user → Generate Access Token con permessi whatsapp_business_messaging, (7) copia token (inizia con EAAG...). Token ha scadenza - usa permanent token per produzione.
Sì, obbligatorio. Numero WhatsApp Business API non può essere usato contemporaneamente su app WhatsApp normale. Devi dedicare un numero telefonico esclusivo alla Business API. Opzioni: (1) acquista SIM nuova dedicata, (2) usa numero fisso aziendale esistente, (3) usa virtual number da provider VoIP. Dopo registrazione in Meta Business Manager, numero è bloccato su API - no app WhatsApp.
Sì, parzialmente. Meta offre numero test e template pre-approvati in sandbox mode: (1) usa account test Meta Business Manager, (2) numero test fornito da Meta (non tuo), (3) template "hello_world" già approvato, (4) puoi inviare a max 5 numeri whitelisted. Sandbox GRATIS ma limitato. Per produzione: serve verifica business Meta (ID azienda, documenti, review 1-3 giorni).
WhatsApp supporta Markdown semplificato: *grassetto* diventa grassetto, _corsivo_ diventa corsivo, ~barrato~ diventa barrato. Esempio template: "Conferma *appuntamento* per _{{1}}_" rende "appuntamento" grassetto e parametro corsivo. NO HTML, NO emoji custom. Emoji Unicode standard supportate: 👍✅📧. Evita formattazione eccessiva - template con troppo formatting possono essere rifiutati da Meta review.
API restituisce errore: numero non registrato su WhatsApp. Messaggio NON viene consegnato, NON viene addebitata conversazione. L'assistente AI4CALL dovrebbe gestire errore gracefully: "impossibile inviare WhatsApp, uso metodo alternativo (SMS/Email)". Best practice: prima di inviare WhatsApp, verifica numero è WhatsApp-enabled o implementa fallback automatico a SMS se WhatsApp fallisce.
L'assistente può orchestrare multi-channel: (1) workflow primario: invia conferma WhatsApp, (2) se fallisce (numero non WhatsApp / consegna failed): fallback automatico a Email SMTP, (3) se Email fallisce: fallback a SMS. Istruisci nel prompt: "priorità comunicazione: 1.WhatsApp, 2.Email, 3.SMS. Prova in ordine fino a successo". Per notifiche urgenti: invia simultaneo WhatsApp + Email per ridondanza.
Sì. Nome business appare sopra i messaggi in chat WhatsApp cliente. Configurazione: Meta Business Manager → WhatsApp → Settings → Display Name. Deve essere nome legale business o brand riconoscibile. Meta review il nome (1-3 giorni) - evita nomi generici/misleading. Dopo approvazione, tutti messaggi mostrano questo nome. Badge verde verificato appare solo dopo verifica Meta Official Business Account (requisiti aggiuntivi).
WhatsApp Business API è mono-direzionale in AI4CALL: assistente INVIA messaggi ma NON legge risposte in tempo reale durante chiamata. Per gestire risposte: (1) configura webhook in Meta Business Manager per ricevere messaggi entranti, (2) integra con n8n/Zapier per processare risposte, (3) salva su CRM o invia notifica team. Alternativa: istruisci template a non richiedere risposta ("Messaggio informativo, no reply needed").
WhatsApp supporta tutte lingue Unicode, ma template devono essere creati per lingua specifica. Esempio: template in inglese "appointment_reminder_en", template in italiano "appointment_reminder_it". Meta richiede traduzioni separate - non auto-traduce. Per business multilingua: crea template per ogni lingua, l'assistente AI4CALL seleziona template basato su lingua cliente (rilevata da conversazione o numero prefix).
Tecnologia e persone:
insieme, zero attese e mille soluzioni.
Pronto a trasformare
le tue chiamate?
Richiedi una demo gratuita e scopri come AI4CALL può rivoluzionare il tuo business