UC-023 — Segmentazione Contatti Avanzata

Campo	Valore
ID	UC-023
Obiettivo	Segmentare contatti con filtri avanzati per creare liste mirate
Canale	Tutti
Complessità	⭐⭐⭐ Avanzato
Tempo stimato	30 minuti
API coinvolte	GET /api/partner-gateway/v1/contacts, POST /contacts, PUT /contacts/{id}, DELETE /contacts/{id}, POST /contacts/list/contacts

Scenari reali

• TurismoVeneto — Segmentare per regione: Filtra i 20.000 contatti per regione di residenza e crea liste separate per Lombardia, Veneto ed Emilia-Romagna per promozioni geolocalizzate.
• LuxuryStore — Lista VIP: Identifica i clienti con spesa totale superiore a 5.000 EUR e crea una lista VIP per anteprime esclusive e inviti a eventi privati.
• FreshMarket — Filtrare per ultimo acquisto: Seleziona i clienti che non acquistano da oltre 90 giorni per una campagna di re-engagement con coupon sconto.

Flusso di segmentazione

Il diagramma mostra il flusso: dalla lista completa si applicano filtri multipli (regione, attributi, data) per creare liste segmentate pronte per le campagne.

Prerequisiti

• API Key attiva con permessi gestione contatti
• Contatti importati nella piattaforma (vedi UC-007)
• Almeno una lista contatti esistente con campi custom valorizzati

Step 1 — Recupera contatti con filtri

Interroga i contatti applicando filtri per regione.

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts?region=Lombardia&limit=50&offset=0" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Contatti filtrati

{
  "contacts": [
    {
      "id": "cnt-001",
      "firstName": "Marco",
      "lastName": "Rossi",
      "phoneNumber": "+393471234567",
      "email": "marco.rossi@email.it",
      "region": "Lombardia",
      "customFields": {
        "lastPurchaseDate": "2026-03-15",
        "totalSpent": 1250.00,
        "preferredChannel": "WHATSAPP"
      }
    },
    {
      "id": "cnt-002",
      "firstName": "Laura",
      "lastName": "Bianchi",
      "phoneNumber": "+393489876543",
      "email": "laura.bianchi@email.it",
      "region": "Lombardia",
      "customFields": {
        "lastPurchaseDate": "2026-01-10",
        "totalSpent": 6800.00,
        "preferredChannel": "SMS"
      }
    }
  ],
  "total": 4350,
  "limit": 50,
  "offset": 0
}

Dietro le quinte — Filtri disponibili e logica di query

1. Filtri standard: region, city, firstName, lastName, email, phoneNumber sono filtrabili direttamente come query parameter.
2. Campi custom: I campi in customFields possono essere filtrati usando la sintassi customFields.nomecampo=valore.
3. Paginazione: Usa limit e offset per paginare risultati di grandi dimensioni. Il massimo per limit e 100.
4. Ordinamento: Usa sort=campo&order=asc|desc per ordinare i risultati (es. sort=customFields.totalSpent&order=desc).
5. Combinazione filtri: Tutti i filtri sono in AND logico. Per logiche OR complesse, esegui più query e combina i risultati lato client.

Step 2 — Crea una lista segmentata

Crea una nuova lista destinata al segmento identificato.

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/list \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "VIP Lombardia - Spesa > 5000 EUR",
    "description": "Clienti lombardi con spesa totale superiore a 5000 EUR"
  }'

Response — Lista creata

{
  "id": "list-vip-lombardia-001",
  "name": "VIP Lombardia - Spesa > 5000 EUR",
  "description": "Clienti lombardi con spesa totale superiore a 5000 EUR",
  "contactCount": 0,
  "createdAt": "2026-04-09T11:00:00+02:00"
}

Step 3 — Aggiungi contatti alla lista segmentata

Aggiungi i contatti filtrati alla nuova lista usando il loro ID.

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/list/contacts \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "listId": "list-vip-lombardia-001",
    "contactIds": ["cnt-002", "cnt-015", "cnt-089", "cnt-142", "cnt-278"]
  }'

Response — Contatti aggiunti

{
  "listId": "list-vip-lombardia-001",
  "addedContacts": 5,
  "duplicateContacts": 0,
  "invalidContacts": 0,
  "totalContactsInList": 5
}

:::tip Automazione della segmentazione Per liste di grandi dimensioni, automatizza il processo lato server: recupera tutti i contatti filtrati con paginazione, raccogli gli ID e inviali in batch alla lista. Il limite per batch e 1.000 contatti. :::

Risultato atteso

Step	Azione	Risultato
1	GET /contacts?region=Lombardia	Lista filtrata di contatti lombardi
2	POST /contacts/list	Nuova lista segmentata creata
3	POST /contacts/list/contacts	Contatti VIP aggiunti alla lista

Esempio completo end-to-end

# 1. Recupera contatti VIP lombardi (paginando)
CONTACTS=$(curl -s -X GET \
  "https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts?region=Lombardia&limit=100&offset=0" \
  -H "X-Api-Key: YOUR_API_KEY")

# 2. Filtra lato client per spesa > 5000 EUR
VIP_IDS=$(echo "$CONTACTS" | jq -r '[.contacts[] | select(.customFields.totalSpent > 5000) | .id] | join(",")')
echo "VIP IDs: $VIP_IDS"

# 3. Crea la lista segmentata
LIST_ID=$(curl -s -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/list \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "VIP Lombardia - Spesa > 5000 EUR",
    "description": "Segmento VIP per campagna esclusiva"
  }' | jq -r '.id')

echo "List ID: $LIST_ID"

# 4. Aggiungi contatti alla lista
IDS_JSON=$(echo "$CONTACTS" | jq '[.contacts[] | select(.customFields.totalSpent > 5000) | .id]')

curl -s -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/list/contacts \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d "{
    \"listId\": \"${LIST_ID}\",
    \"contactIds\": ${IDS_JSON}
  }" | jq .

Varianti

Segmentazione per inattivita (re-engagement)

Filtra contatti che non acquistano da oltre 90 giorni:

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts?customFields.lastPurchaseDate.before=2026-01-09&limit=100" \
  -H "X-Api-Key: YOUR_API_KEY"

Rimuovere un contatto da una lista

Se un contatto non deve più appartenere a un segmento:

curl -X DELETE "https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/list/contacts?listId=list-vip-lombardia-001&contactId=cnt-278" \
  -H "X-Api-Key: YOUR_API_KEY"

Errori comuni

400 Bad Request — Filtro non valido

{
  "status": "fail",
  "data": {
    "filter": "Unknown filter field: invalidField"
  }
}

Soluzione: Verifica i nomi dei campi filtrabili. Per i custom fields usa la sintassi customFields.nomeCampo.

404 Not Found — Contatto non trovato

{
  "status": "fail",
  "data": {
    "contactId": "Contact not found: cnt-999"
  }
}

Soluzione: L'ID del contatto potrebbe essere stato eliminato o non esistere. Verifica l'ID con una GET prima dell'aggiunta alla lista.

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-007 — Gestione Contatti e Liste: Import contatti da CSV e VCard
• UC-006 — Campagna SMS Bulk: Usa la lista segmentata in una campagna SMS
• UC-022 — Campagna Bulk WhatsApp: Invia alla lista VIP tramite WhatsApp
• UC-028 — Compliance Opt-out GDPR: Gestisci opt-out e conformita GDPR

Riferimenti

• API Reference — Contacts: Documentazione completa endpoint contatti
• Guida Contatti e Liste: Best practice per la gestione dei contatti
• Guida Autenticazione: Dettagli su API Key e Basic Auth