UC-024 — Template con Link Tracciati

Campo	Valore
ID	UC-024
Obiettivo	Creare template WhatsApp con bottoni tracciati per misurare il CTR
Canale	WhatsApp
Complessità	⭐⭐⭐ Avanzato
Tempo stimato	30 minuti
API coinvolte	`POST /api/message-server/whatsapp/templates`, `POST /api/message-server/whatsapp/send`

Scenari reali

ShopItalia — Misurare CTR: Traccia quanti utenti cliccano sul bottone "Vai allo shop" nel template promozionale per calcolare il conversion rate della campagna.
TravelDream — Tracking landing page: Ogni destinatario riceve un link univoco alla landing page dell'offerta viaggio, con parametri UTM per analisi in Google Analytics.
MarketingPro — A/B testing link: Invia due varianti del template con link diversi (landing A vs landing B) per determinare quale converte meglio.

Flusso del template con link tracciati

Il diagramma mostra il ciclo completo: creazione del template con tracking, invio al destinatario e cattura del click con redirect trasparente alla landing page.

Prerequisiti

API Key attiva con permessi template WhatsApp
Numero WhatsApp Business verificato (vedi UC-025)
Landing page HTTPS pronta per il tracking
Familiarita con i template WhatsApp (vedi UC-013)

Step 1 — Crea il template con link tracciati

Crea un template WhatsApp con trackButtonLinks: true per abilitare il tracking automatico dei click.

curl -X POST https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "promo_estate_tracked_2026",
    "language": "it",
    "category": "MARKETING",
    "components": [
      {"type": "HEADER", "format": "IMAGE",
       "example": {"header_handle": ["https://cdn.shopitalia.it/promo/estate-2026-header.jpg"]}},
      {"type": "BODY",
       "text": "Ciao {{1}}, i saldi estivi sono arrivati! Sconto {{2}} su tutta la collezione fino al {{3}}.",
       "placeholderFields": [
         {"index": 1, "label": "Nome cliente", "example": "Marco"},
         {"index": 2, "label": "Percentuale sconto", "example": "50%"},
         {"index": 3, "label": "Data scadenza", "example": "30 giugno"}]},
      {"type": "BUTTONS", "buttons": [
        {"type": "URL", "text": "Vai allo shop",
         "url": "https://shopitalia.it/promo/estate2026?utm_source=whatsapp&utm_campaign={{1}}",
         "example": ["promo_estate"]}]}
    ],
    "trackButtonLinks": true
  }'

Response — Template sottomesso

{
  "templateId": "promo_estate_tracked_2026",
  "name": "promo_estate_tracked_2026",
  "status": "PENDING",
  "language": "it",
  "category": "MARKETING",
  "trackButtonLinks": true,
  "createdAt": "2026-04-09T12:00:00+02:00"
}

:::info Approvazione Meta Il template deve essere approvato da Meta prima dell'uso. Il processo richiede tipicamente da pochi minuti a 24 ore. Monitora lo stato con una GET sul template. :::

Dietro le quinte — Come funziona il tracking dei link

URL rewriting: Quando trackButtonLinks: true e attivo, il gateway sostituisce l'URL originale del bottone con un URL di tracking intermedio (es. https://trk.agiletelecom.com/c/abc123).
Click capture: Quando il destinatario clicca il bottone, la richiesta passa dal tracking service che registra: timestamp, destinatario, template, campagna.
Redirect trasparente: Dopo aver registrato il click, il tracking service esegue un redirect HTTP 302 verso l'URL originale della landing page.
Parametri UTM: I parametri UTM nell'URL originale vengono preservati nel redirect, permettendo l'attribuzione in Google Analytics o altri strumenti di analisi.
Metriche disponibili: Click totali, click unici, CTR (click/delivered), tempo medio al click, distribuzione oraria dei click.

Step 2 — Invia il messaggio con template tracciato

Una volta approvato il template, invia il messaggio con i parametri personalizzati.

curl -X POST https://lora-api.agiletelecom.com/api/message-server/whatsapp/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393471234567",
    "templateId": "promo_estate_tracked_2026",
    "language": "it",
    "components": [
      {
        "type": "HEADER",
        "parameters": [
          {"type": "image", "image": {"link": "https://cdn.shopitalia.it/promo/estate-2026-header.jpg"}}
        ]
      },
      {
        "type": "BODY",
        "parameters": [
          {"type": "text", "text": "Marco"},
          {"type": "text", "text": "50%"},
          {"type": "text", "text": "30 giugno"}
        ]
      },
      {
        "type": "BUTTON",
        "sub_type": "URL",
        "index": 0,
        "parameters": [
          {"type": "text", "text": "promo_estate"}
        ]
      }
    ]
  }'

Response — Messaggio inviato con tracking

{
  "messageId": "wa-msg-trk-2026-04-09-001",
  "accepted": true,
  "destination": "+393471234567",
  "templateId": "promo_estate_tracked_2026",
  "trackingEnabled": true,
  "trackedLinks": [
    {
      "buttonIndex": 0,
      "originalUrl": "https://shopitalia.it/promo/estate2026?utm_source=whatsapp&utm_medium=template&utm_campaign=promo_estate",
      "trackingUrl": "https://trk.agiletelecom.com/c/wa-msg-trk-2026-04-09-001-btn0"
    }
  ]
}

:::tip Conserva i trackingUrl Salva i trackingUrl restituiti nella response per correlare i click con i singoli messaggi nel tuo sistema di analytics. :::

Risultato atteso

Step	Azione	Risultato
1	`POST /whatsapp/templates`	Template creato con `trackButtonLinks: true`
2	Approvazione Meta	Stato `APPROVED`
3	`POST /whatsapp/send`	Messaggio inviato con link tracciati
4	Click destinatario	Evento registrato + redirect alla landing

Esempio completo end-to-end

# 1. Crea template con tracking (una tantum, attendi approvazione)
curl -s -X POST https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "promo_estate_tracked_2026",
    "language": "it",
    "category": "MARKETING",
    "components": [
      {"type": "BODY", "text": "Ciao {{1}}, sconto {{2}} fino al {{3}}!",
       "placeholderFields": [
         {"index": 1, "label": "Nome", "example": "Marco"},
         {"index": 2, "label": "Sconto", "example": "50%"},
         {"index": 3, "label": "Scadenza", "example": "30 giugno"}]},
      {"type": "BUTTONS", "buttons": [
        {"type": "URL", "text": "Vai allo shop", "url": "https://shopitalia.it/promo?c={{1}}", "example": ["estate2026"]}]}
    ],
    "trackButtonLinks": true
  }' | jq .

# 2. Dopo approvazione, invia il messaggio
MSG_ID=$(curl -s -X POST https://lora-api.agiletelecom.com/api/message-server/whatsapp/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393471234567",
    "templateId": "promo_estate_tracked_2026",
    "language": "it",
    "components": [
      {"type": "BODY", "parameters": [{"type": "text", "text": "Marco"}, {"type": "text", "text": "50%"}, {"type": "text", "text": "30 giugno"}]},
      {"type": "BUTTON", "sub_type": "URL", "index": 0, "parameters": [{"type": "text", "text": "estate2026"}]}
    ]
  }' | jq -r '.messageId')

echo "Message ID: $MSG_ID"

Varianti

Template con più bottoni tracciati

Traccia click su bottoni multipli per capire quale CTA converte meglio:

curl -X POST https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "multi_cta_tracked_2026",
    "language": "it",
    "category": "MARKETING",
    "components": [
      {"type": "BODY", "text": "Ciao {{1}}, scopri le nostre offerte!"},
      {
        "type": "BUTTONS",
        "buttons": [
          {"type": "URL", "text": "Offerte donna", "url": "https://shop.it/donna?c={{1}}", "example": ["spring"]},
          {"type": "URL", "text": "Offerte uomo", "url": "https://shop.it/uomo?c={{1}}", "example": ["spring"]}
        ]
      }
    ],
    "trackButtonLinks": true
  }'

Errori comuni

400 Bad Request — placeholderFields mancanti

{
  "status": "fail",
  "data": {
    "placeholderFields": "Placeholder fields are required when body contains variables"
  }
}

Soluzione: Ogni variabile {{N}} nel testo del body richiede un corrispondente oggetto in placeholderFields con index, label e example.

400 Bad Request — URL bottone non valido

{
  "status": "fail",
  "data": {
    "buttons": "Button URL must be a valid HTTPS URL"
  }
}

Soluzione: L'URL del bottone deve iniziare con https://. URL con protocollo HTTP o senza protocollo vengono rifiutati.

401 Unauthorized — API Key mancante o non valida

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing API key"
  }
}

Soluzione: Verifica che l'header X-Api-Key sia presente e che la chiave sia attiva nel pannello della piattaforma.

Prossimi passi

UC-013 — WhatsApp Template Workflow: Ciclo completo di gestione template
UC-022 — Campagna Bulk WhatsApp: Usa template tracciati in campagne bulk
UC-029 — Report Campagna Completo: Analizza CTR e metriche post-campagna
UC-004 — Verifica Delivery Status: Monitora consegna e lettura

Riferimenti

API Reference — WhatsApp Templates: Documentazione completa endpoint template
Guida WhatsApp: Specifiche del canale WhatsApp
Guida Autenticazione: Dettagli su API Key e Basic Auth

Scenari reali​

Flusso del template con link tracciati​

Prerequisiti​

Step 1 — Crea il template con link tracciati​

Response — Template sottomesso​

Step 2 — Invia il messaggio con template tracciato​

Response — Messaggio inviato con tracking​

Risultato atteso​

Esempio completo end-to-end​

Varianti​

Template con più bottoni tracciati​

Errori comuni​

400 Bad Request — placeholderFields mancanti​

400 Bad Request — URL bottone non valido​

401 Unauthorized — API Key mancante o non valida​

Prossimi passi​

Riferimenti​