Con Papo (https://papo.global/), puoi usare l'API REST per inviare modelli di messaggio approvati (HSM) su WhatsApp, automatizzando notifiche transazionali e campagne senza accedere all'interfaccia. L'API consente di elencare le caselle di posta Cloud API del tuo account, recuperare i modelli approvati da Meta e inviarli a uno o più contatti, a condizione che tu abbia un token API e i modelli siano sincronizzati sulla piattaforma.
| Azione API | Cosa fa | Esempio d'uso |
|---|---|---|
| Elenca caselle WhatsApp | Restituisce le caselle di posta WhatsApp Cloud API associate all'account | Selezionare la casella corretta prima dell'invio |
| Elenca template approvati | Restituisce i modelli di messaggio (HSM) con stato "approvato" per una determinata inbox | Verificare gli HSM disponibili per l'invio |
| Invia HSM a un contatto | Invia un modello approvato a un singolo numero di telefono, compilando le variabili | Notifica ordine, promemoria appuntamento |
| Invia HSM a più contatti | Invia lo stesso modello a una lista di contatti in una sola volta | Campagna di marketing, comunicazione di massa |
Come funziona l'invio di HSM tramite API
L'API di Papo rispecchia le funzionalità della piattaforma. Per inviare un modello di messaggio WhatsApp, non devi creare nulla di nuovo tramite codice: i modelli vengono creati e inviati direttamente nel Gestore Business di Meta e, una volta approvati, appaiono automaticamente nel tuo account Papo. L'API si limita a consultare l'elenco dei modelli approvati ed effettuare l'invio.
Il flusso tipico di integrazione consiste in:
- Generare un token API nel pannello di Papo.
- Identificare la casella di posta WhatsApp Cloud API in cui il modello è stato sincronizzato.
- Ottenere l'elenco dei modelli approvati (HSM) di quella casella.
- Preparare la richiesta con i parametri necessari: ID del modello, lingua, numero del destinatario con prefisso internazionale e i valori delle variabili (se il modello contiene
{{1}},{{2}}ecc.). - Inviare la richiesta — sia a un singolo contatto che a un insieme di numeri, ciascuno con le proprie variabili personalizzate.
Passo dopo passo per utilizzare l'API
1. Genera un token API
Nel menu delle impostazioni del tuo account Papo, accedi alla sezione API o token di accesso. Crea un token con le autorizzazioni necessarie per gestire conversazioni e messaggi. Conserva il token in un luogo sicuro; verrà inviato nell'intestazione di tutte le richieste.
2. Elenca le caselle WhatsApp disponibili
Prima di inviare qualsiasi modello, devi sapere quale casella di posta (inbox) contiene i modelli approvati. Utilizza l'endpoint che restituisce le caselle WhatsApp Cloud API del tuo account. Annota l'identificativo della casella che intendi usare — sarà obbligatorio nei passaggi successivi.
3. Consulta i modelli approvati (HSM)
Con l'identificativo della casella in mano, chiama l'endpoint che elenca i template con stato APPROVED. La risposta fornirà per ogni modello il nome, la lingua disponibile, la categoria (Marketing, Utilità o Autenticazione) e i parametri attesi. Questo passaggio è importante per confermare che il modello sia abilitato e per sapere quali variabili compilare.
4. Prepara la richiesta di invio
L'operazione di invio a un singolo contatto richiede essenzialmente:
- L'ID del modello (o il nome, a seconda dell'implementazione).
- La lingua del modello (ad esempio,
pt_BR). - Il numero di telefono del contatto, incluso il prefisso internazionale (es.:
5511999999999). - Un oggetto con i valori delle variabili, se il modello contiene segnaposto.
Per l'invio in blocco (più contatti), la chiamata accetta una lista di destinatari, ciascuno con il proprio numero e, opzionalmente, le proprie variabili. Il modello è lo stesso per tutti.
5. Invia e verifica la risposta
L'API restituisce una conferma sincrona che la richiesta di invio è stata accettata. Per monitorare lo stato reale di consegna (consegnato, letto, fallito), puoi configurare un webhook outbound — Papo notifica in tempo reale gli eventi della conversazione. L'articolo sulla ricezione di eventi in tempo reale (elencato in "Leggi anche") spiega come attivare questa funzione.
Chi dovrebbe usare l'API per l'invio di HSM
Qualsiasi azienda che desideri automatizzare le comunicazioni transazionali da sistemi esterni trae beneficio dall'API. Invece di dipendere dall'interfaccia di Papo per ogni notifica, puoi integrare l'invio direttamente nel tuo ERP, CRM o piattaforma di e-commerce. Esempi comuni:
- Conferma d'acquisto o aggiornamento dello stato dell'ordine.
- Promemoria di visita o appuntamento inviato 24 ore prima.
- Sollecito di pagamento di fattura scaduta con il link di pagamento.
- Comunicazione di modifica volo o prenotazione.
L'API è particolarmente utile quando la regola che determina quando inviare il modello risiede in un altro software — ad esempio, un sistema di logistica che invia la notifica di consegna non appena il pacchetto esce per il trasporto.
Domande frequenti
L'API di Papo ha un costo aggiuntivo?
L'API è disponibile nei piani di Papo. Puoi generare token e utilizzare gli endpoint in base al piano sottoscritto. I dettagli su limiti e tariffe per richiesta sono nella pagina dei piani e nella documentazione dell'API.
Devo creare i modelli di messaggio tramite API?
No. I modelli devono essere creati e sottoposti all'approvazione nel Gestore Business di Meta. Una volta approvati, vengono sincronizzati automaticamente in Papo e appaiono nell'elenco dei template dell'API.
Posso inviare HSM a numeri che non sono nel CRM di Papo?
Sì. Il destinatario non deve essere previamente registrato nel CRM della piattaforma. Basta inserire il numero di WhatsApp (con prefisso internazionale e locale) nella richiesta. Tuttavia, devi avere il consenso (opt-in) del cliente a ricevere la comunicazione, specialmente se il modello è di categoria Marketing.
Come faccio a sapere se il messaggio è stato consegnato?
La risposta immediata dell'API conferma che la richiesta è stata accettata e inviata a WhatsApp. Per monitorare fallimenti, consegne e letture in tempo reale, è necessario attivare il webhook di eventi (outbound) di Papo. Consulta la guida sui webhook nella centro assistenza.
Esiste un limite di velocità per gli invii tramite API?
Sì. Papo applica limiti di velocità per proteggere la stabilità del servizio e rispettare le politiche di WhatsApp. Si consiglia di mantenere velocità moderate — evitare picchi improvvisi aiuta a preservare la salute del numero. I valori esatti sono nella documentazione dell'API.
Posso usare l'API per campagne di marketing di massa?
Sì, a condizione che utilizzi esclusivamente modelli approvati di categoria Marketing e abbia l'opt-in esplicito dei destinatari. Inviare messaggi indesiderati può generare segnalazioni e mettere il tuo numero a rischio di blocco. Pianifica gli invii con controllo della cadenza e rispetta sempre le politiche di WhatsApp.
Leggi anche
- Come ricevere eventi in tempo reale da Papo tramite Webhook (outbound)
- Come usare l'API di Papo per creare e aggiornare contatti in massa
Inizia ad automatizzare i tuoi invii di HSM ora – prova gratis →
Crea il tuo account Papo e invia modelli di messaggio approvati senza costi per il primo utente.