ITA – WHATSAPP REST API (Universal Mode)

Cos’è WhatsApp Business API (per chi parte da zero) #

WhatsApp Business API consente alle aziende di inviare e ricevere messaggi su WhatsApp in modo programmatico. A differenza dell’app WhatsApp Business, l’API permette integrazioni automatiche, invio massivo tramite template approvati da Meta, e gestione di conversazioni bidirezionali con i clienti.

Perché WhatsApp Business API #

• Mittente verificato: nome e badge del WhatsApp Business Account.
• Contenuti ricchi: testo, immagini, video, documenti, posizione, sticker, bottoni interattivi.
• Template approvati: messaggi pre-approvati da Meta per comunicazioni proattive (marketing, utility, autenticazione).
• Conversazione: gestisci le risposte dell’utente in tempo reale entro la finestra di 24 ore.
• Fallback multicanale: se WhatsApp non consegna, puoi ricadere su RCS e/o SMS automaticamente.

Quando usarlo #

• Notifiche transazionali (conferme ordine, OTP, aggiornamenti spedizione).
• Campagne marketing (promozioni, offerte personalizzate con placeholder).
• Assistenza clienti conversazionale (messaggi liberi nella finestra 24h).

Requisiti: account WhatsApp Business configurato sulla piattaforma AgileTelecom; API Key o credenziali Basic Auth; template approvati da Meta per messaggi proattivi.

Come usare questa guida #

• Chi: pensata anche per lettori non tecnici.
• Come: esempi brevi, JSON minimali, tabelle di riferimento per ogni oggetto.
• Collection Postman/Bruno: importa la collection ufficiale per provare subito gli endpoint.

Autenticazione e sicurezza #

• Protocollo – HTTPS obbligatorio
• Auth opzione 1 – API Key in header (X-Api-Key)
• Auth opzione 2 – Basic Auth in header (Authorization: Basic)

Installazione della Collection #

Postman #

1. Scarica e installa Postman
2. Apri Postman
3. Clicca su Import (in alto a sinistra)
4. Trascina il file AgileTelecom_WhatsApp_API.postman_collection.json nella finestra oppure clicca Upload Files e selezionalo
5. La collection apparirà nella barra laterale sinistra sotto Collections

Bruno #

1. Scarica e installa Bruno
2. Apri Bruno
3. Clicca su Open Collection
4. Seleziona la cartella AgileTelecom_WhatsApp_API (quella che contiene il file bruno.json)
5. La collection si aprirà con tutta la struttura di cartelle

Configurazione variabili #

Postman #

1. Clicca con il tasto destro sulla collection AgileTelecom WhatsApp API > Edit
2. Vai alla tab Variables
3. Compila i campi indicati nella tabella seguente
4. Salva con Ctrl+S

Bruno #

1. Clicca sull’icona Environments (in alto a destra)
2. Seleziona Production (o crea un nuovo environment)
3. Compila le stesse variabili della tabella sopra
4. Per Basic Auth: la variabile BASIC_AUTH deve contenere la codifica Base64 di username:password
   • Puoi generarla con: echo -n "username:password" | base64

Quickstart #

1. Scegli il tipo di autenticazione: apri la cartella Auth: API Key oppure Auth: Basic.
2. Recupera il tuo phoneNumberId: esegui Get All Phone Numbers e prendi nota del campo id.
3. Recupera i template disponibili: esegui Get All Templates.
4. Invia il primo messaggio: scegli una delle richieste nella cartella 3. Send Messages.

GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers
Authorization: X-Api-Key: <API_KEY>

La risposta contiene l’elenco dei numeri WhatsApp Business associati al tuo account. Prendi il valore del campo id del numero che vuoi usare come mittente.

Struttura della Collection #

AgileTelecom WhatsApp API
|
+-- Auth: API Key             <-- Chiamate con header X-Api-Key
|   +-- 1. Phone Numbers
|   +-- 2. Templates
|   +-- 3. Send Messages
|   +-- 4. Media
|
+-- Auth: Basic               <-- Chiamate con header Authorization: Basic
|   +-- 1. Phone Numbers
|   +-- 2. Templates
|   +-- 3. Send Messages
|   +-- 4. Media
|
+-- Webhook Examples          <-- Esempi di callback (NON da eseguire)
    +-- Delivery Notification
    +-- Read Notification
    +-- Inbound Text Message
    +-- Inbound Media Message

Phone Numbers #

Get All Phone Numbers #

GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers
Authorization: X-Api-Key: <API_KEY>

Restituisce la lista di tutti i numeri WhatsApp Business associati al tuo account. Dalla risposta prendi il valore del campo id del numero che vuoi usare come mittente: sarà il phoneNumberId da inserire nelle richieste di invio.

Get Phone Number by ID #

GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers/{id}
Authorization: X-Api-Key: <API_KEY>

Restituisce i dettagli di un singolo numero WhatsApp Business (nome visualizzato, stato, scope).

Templates (CRUD) #

Lista #

La lista è fornita in modalità paginata. Puoi filtrare per category (MARKETING, UTILITY, AUTHENTICATION) e status (APPROVED, PENDING, REJECTED, PAUSED, DISABLED).

GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates?page=0&size=20
Authorization: X-Api-Key: <API_KEY>

Dettaglio #

Restituisce il dettaglio completo di un template, inclusi i componenti (header, body, footer, bottoni).

GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates/{id}
Authorization: X-Api-Key: <API_KEY>

Creazione #

Crea un nuovo template WhatsApp. Il template deve essere approvato da Meta prima di poter essere utilizzato per l’invio. Il parametro query phoneNumberId specifica a quale numero WhatsApp Business associare il template.

POST https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates?phoneNumberId={phoneNumberId}
Authorization: X-Api-Key: <API_KEY>
Content-Type: application/json

Campi della richiesta di creazione template #

Oggetto buttons[] #

Oggetto placeholderFields #

Usato per definire link tracciati (short link) nel body del template. La struttura è:

"placeholderFields": {
    "WHATSAPP": {
        "shortLinkT1": "https://www.example.com/landing-page"
    }
}

Il placeholder {shortLinkT1} nel body del template verrà sostituito con un link tracciato (short link) che punta all’URL indicato. Questo permette di monitorare i click.

Esempi di creazione template #

Template semplice con testo #

{
    "name": "marketing_Welcome",
    "lang": "it",
    "category": "MARKETING",
    "headerText": "Welcome",
    "body": "Ciao {firstName} siamo contentissimo di averti tra noi",
    "footer": "Per info visita il sito"
}

Template con bottoni #

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerText": "Welcome",
  "body": "Ciao {firstName} siamo contentissimo di averti tra noi",
  "footer": "Per info visita il sito",
  "buttons": [
    {
      "type": "URL",
      "text": "Apri il sito",
      "url": "https://agiletelecom.com/"
    },
    {
      "type": "PHONE_NUMBER",
      "text": "Chiamaci",
      "phoneNumber": "+39 123123123"
    },
    {
      "type": "QUICK_REPLY",
      "text": "Voglio essere contattato"
    }
  ]
}

Template con header immagine #

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerFormat": "IMAGE",
  "headerMediaUrl": "https://example.com/image.jpg",
  "body": "Ciao {firstName} siamo contentissimo di averti tra noi",
  "footer": "Per info visita il sito"
}

Template con link tracciato nel body #

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerFormat": "IMAGE",
  "headerMediaUrl": "https://example.com/image.jpg",
  "body": "Ciao {firstName} siamo contentissimo di averti tra noi. Clicca qui {shortLinkT1} per accedere all'area riservata.",
  "footer": "Per info visita il sito",
  "placeholderFields": {
    "WHATSAPP": {
      "shortLinkT1": "https://www.example.com/landing-page"
    }
  }
}

Template con link tracciato nel bottone #

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerFormat": "IMAGE",
  "headerMediaUrl": "https://example.com/image.jpg",
  "body": "Ciao {firstName} siamo contentissimo di averti tra noi.",
  "footer": "Per info visita il sito",
  "buttons": [
    {
      "type": "URL",
      "text": "Apri il sito",
      "url": "https://agiletelecom.com/"
    }
  ],
  "trackButtonLinks": true
}

Modifica e cancellazione template #

Update Template #

Aggiorna un template esistente. Solo i campi forniti nel body vengono modificati.

PATCH https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates/{id}
Authorization: X-Api-Key: <API_KEY>
Content-Type: application/json

{
    "headerText": "Suuuper Welcome",
    "body": "Ciao {firstName} siamo gasatissimi di averti tra noi",
    "footer": "Sul nostro sito trovi tutte le info"
}

Delete Template #

Elimina un template WhatsApp.

DELETE https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates/{id}
Authorization: X-Api-Key: <API_KEY>

Invio dei messaggi #

Tutte le richieste di invio condividono gli stessi campi principali. Il contenuto del messaggio viene specificato tramite body oppure template (mutuamente esclusivi: uno dei due è obbligatorio, ma non entrambi).

POST https://lora-api.agiletelecom.com/api/message-server/whatsapp/send
Authorization: X-Api-Key: <API_KEY>
Content-Type: application/json

Campi principali della richiesta #

Oggetto template #

Usato per inviare un messaggio basato su un template approvato da Meta.

Oggetto body #

Usato per inviare un messaggio libero. Deve contenere uno e uno solo dei seguenti sotto-oggetti:

Nota: I messaggi liberi (non template) possono essere inviati solo entro la finestra di 24 ore dall’ultimo messaggio ricevuto dall’utente.

body > text #

body > image #

body > document #

body > video #

body > audio #

body > sticker #

body > location #

body > reaction #

Oggetto fallbackSms #

Se WhatsApp non riesce a consegnare il messaggio, il sistema invia un SMS di fallback.

Oggetto fallbackRcs #

Se WhatsApp non riesce a consegnare, il sistema prova prima con RCS, poi con SMS.

Regola: Se fallbackRcs è presente, fallbackSms è obbligatorio.

Descrizione delle richieste nella collection #

Send with Template — Invia un messaggio utilizzando un template approvato da Meta. È il modo più semplice per inviare un messaggio.

Send with Template + Placeholder + Media — Invia un template con valori dinamici (placeholder) e un’immagine nell’header. I placeholder nel template vengono sostituiti con i valori forniti nella mappa placeholders.

Send Text Message — Invia un messaggio di testo libero. Utilizzabile solo nella finestra 24h dall’ultimo messaggio dell’utente.

Send Image — Invia un’immagine con didascalia opzionale. Fornire url (URL pubblico) oppure key (chiave media interna), mai entrambi.

Send Document — Invia un documento (PDF, DOC, ecc.) con nome file visualizzato dal destinatario e didascalia opzionale.

Send Location — Invia una posizione geografica visualizzata su mappa.

Send with Fallback SMS — Invia un messaggio WhatsApp e, se non può essere consegnato, il sistema invia automaticamente un SMS di fallback con il testo indicato in fallbackSms.

Send with Fallback RCS + SMS — Invia con catena di fallback completa: WhatsApp → RCS → SMS. Se WhatsApp fallisce, prova RCS; se anche RCS fallisce, invia SMS.

Send Template with tracked link — Invia un template che contiene un link tracciato nel body. Il placeholder shortLinkT1 nel campo placeholders specifica l’URL di destinazione reale. Il sistema genera automaticamente un short link tracciato che permette di monitorare i click.

{
    "destination": "+39xxxxxxxxxx",
    "phoneNumberId": 5,
    "template": {
        "id": 42
    },
    "placeholders": {
        "shortLinkT1": "https://agiletelecom.com"
    },
    "enableNotification": true
}

Send Template with tracked link in button — Invia un template che contiene un bottone URL con link tracciato. Il funzionamento è identico a “Send Template with tracked link”: il placeholder shortLinkT1 in placeholders definisce l’URL reale di destinazione del bottone, e il sistema genera uno short link tracciato.

{
    "destination": "+39xxxxxxxxxx",
    "phoneNumberId": 5,
    "template": {
        "id": 42
    },
    "placeholders": {
        "shortLinkT1": "https://agiletelecom.com"
    },
    "enableNotification": true
}

Media #

Download Media File #

GET https://lora-api.agiletelecom.com/api/files/{mediaKey}?expireMinutes=180
Authorization: X-Api-Key: <API_KEY>

Restituisce un URL pre-firmato (temporaneo) per scaricare un file media ricevuto in un messaggio inbound. Il parametro expireMinutes indica per quanti minuti l’URL sarà valido (default: 180). Dalla risposta, usa il campo url per scaricare il file con una semplice GET.

Eventi asincroni: Delivery & Read #

Gli esiti finali non arrivano nella risposta immediata all’invio, ma tramite webhook verso l’endpoint configurabile in piattaforma. La risposta all’invio indica solo la presa in carico. L’evento di consegna e/o lettura può essere istantaneo o richiedere anche alcune ore poiché dipende dalla rete, dal telefono e dall’utente stesso.

Queste NON sono chiamate da eseguire. Sono esempi del formato JSON che il sistema AgileTelecom invierà al tuo URL di callback. Devi configurare il tuo URL nella piattaforma AgileTelecom.

Delivery Notification #

Notifica quando un messaggio viene consegnato al destinatario. Campo chiave: statusCode — 3 = consegnato, 6 = non consegnabile.

{
    "channel": "WHATSAPP",
    "eventType": "DELIVERY",
    "messageId": "88116e2f-b8b4-40fe-b727-f453b6b99adc",
    "destination": "+393409997528",
    "statusCode": 3,
    "description": "delivered",
    "eventDate": "2025-10-16T10:42:18Z"
}

Read Notification #

Notifica quando il destinatario legge il messaggio.

{
    "channel": "WHATSAPP",
    "eventType": "READ",
    "messageId": "88116e2f-b8b4-40fe-b727-f453b6b99adc",
    "destination": "+393409997528",
    "eventDate": "2025-10-16T10:42:18Z"
}

Messaggi in entrata (Inbound) e Media #

Le risposte dell’utente e i contenuti multimediali arrivano al tuo endpoint Inbound. La sorgente (source) è il numero di telefono dell’utente che risponde, mentre la destinazione (destination) è il numero WhatsApp Business che riceve il messaggio.

Inbound Text Message #

Notifica quando l’utente risponde con un messaggio di testo. Campi chiave: source (chi ha scritto), text (contenuto del messaggio).

{
    "channel": "WHATSAPP",
    "eventType": "INBOUND",
    "messageId": "wamid.HBxxxxxxxxxxxxxxxxx",
    "source": "+393471488489",
    "destination": "+393209998877",
    "receivedDate": "2025-10-31T10:59:05.099Z",
    "messageType": "TEXT",
    "text": "Messaggio di risposta dell'utente"
}

Inbound Media Message #

Notifica quando l’utente invia un’immagine, audio o video. Campo chiave: mediaKey — usa questo valore con l’endpoint Download Media File per scaricare il file.

{
    "channel": "WHATSAPP",
    "eventType": "INBOUND",
    "source": "+393471488489",
    "destination": "+393209998877",
    "receivedDate": "2025-10-31T11:00:41.003Z",
    "messageType": "IMAGE",
    "mediaKey": "b394ab72/efd4987c/39b4879f6fed01f0d622453be1488c93"
}

Risposte di invio #

Tutte le chiamate di invio (/send) restituiscono una risposta con questa struttura:

{
    "messageId": "e76614d1-4ac1-4d94-89f0-d07f1b5a190c",
    "simulation": false,
    "results": {
        "whatsapp": { "accepted": true },
        "rcs": null,
        "sms": null
    }
}

• messageId: ID univoco del messaggio (usalo per tracciare le delivery notification)
• simulation: true se il messaggio era in modalità test
• results.whatsapp.accepted: true se WhatsApp ha accettato il messaggio
• results.rcs: risultato fallback RCS (se configurato)
• results.sms: risultato fallback SMS (se configurato)

Importante: accepted: true significa che il messaggio è stato accettato per l’invio, non che è stato consegnato. La conferma di consegna arriva tramite il callback Delivery Notification.

Codici di errore comuni #

Riferimenti API (indice rapido) #

• Phone Numbers:
  • GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers
  • GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers/{id}
• Templates:
  • GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates?page=0&size=20
  • GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates/{id}
  • POST https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates?phoneNumberId={phoneNumberId}
  • PATCH https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates/{id}
  • DELETE https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates/{id}
• Invio: POST https://lora-api.agiletelecom.com/api/message-server/whatsapp/send (da template o messaggio libero)
• Webhook (verso cliente): Delivery/Read, Inbound (payload lato cliente definibile nella piattaforma web)
• Media: GET https://lora-api.agiletelecom.com/api/files/{mediaKey}?expireMinutes=...

FAQ #