UC-007 — Gestione Contatti e Liste per Campagne

Campo	Valore
ID	UC-007
Obiettivo	Importare contatti, creare liste segmentate e prepararle per l'uso in campagne
Canale	Tutti
Complessità	⭐⭐ Intermedio
Tempo stimato	20 minuti
API coinvolte	`POST/GET/PUT/DELETE /api/partner-gateway/v1/contacts`, `POST/GET /contacts/list`, `POST /contacts/list/contacts`, `POST /contacts/upload`, `POST /contacts/upload/vcard`

Scenari reali

ShopItalia — Import rubrica clienti: Importa l'export dal CRM aziendale (CSV con 5.000 clienti) nella piattaforma per preparare la campagna Black Friday.
TurismoVeneto — Segmentazione per regione: Crea liste separate per clienti di Lombardia, Veneto ed Emilia-Romagna per inviare promozioni geolocalizzate sui soggiorni estivi.
Studio Legale Ferrara — Rubrica da telefono: Importa la rubrica aziendale in formato VCard per inviare comunicazioni istituzionali via SMS.

Flusso di gestione contatti

Il diagramma mostra i tre percorsi di importazione: aggiunta manuale, upload CSV/Excel o import VCard. Tutti convergono nella verifica e nell'utilizzo in campagna.

Step 1 — Crea una lista contatti

Crea una lista vuota che funzionera da contenitore per i contatti.

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": "Clienti Nord Italia",
    "description": "Clienti delle regioni Lombardia, Piemonte, Veneto, Emilia-Romagna"
  }'

Response — Lista creata

{
  "id": 87,
  "name": "Clienti Nord Italia",
  "description": "Clienti delle regioni Lombardia, Piemonte, Veneto, Emilia-Romagna",
  "contactCount": 0,
  "createdAt": "2026-04-09T09:00:00Z"
}

:::tip Salva l'ID lista Il campo id e l'identificativo che userai per aggiungere contatti e associare la lista alle campagne. :::

Step 2a — Aggiungi contatti singolarmente

Crea un nuovo contatto nella rubrica e associalo alla lista.

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "firstName": "Giulia",
    "lastName": "Rossi",
    "phoneNumber": "+393401234567",
    "email": "giulia.rossi@example.it",
    "gender": "F",
    "city": "Milano",
    "province": "MI"
  }'

Response — Contatto creato

{
  "id": 24501,
  "firstName": "Giulia",
  "lastName": "Rossi",
  "phoneNumber": "+393401234567",
  "email": "giulia.rossi@example.it",
  "gender": "F",
  "city": "Milano",
  "province": "MI",
  "valid": true,
  "createdAt": "2026-04-09T09:01:00Z"
}

Associa il contatto alla lista:

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 '{
    "contactIds": [24501],
    "listIds": [87]
  }'

{
  "added": 1,
  "skipped": 0
}

:::info Aggiunta multipla Puoi passare più contactIds e più listIds in una sola richiesta per associare N contatti a M liste contemporaneamente. :::

Step 2b — Import bulk da CSV

Per importazioni massive, carica un file CSV o Excel. Il processo avviene in due fasi: upload con anteprima, poi conferma del mapping.

Formato CSV atteso

nome,cognome,telefono,email,citta
Marco,Bianchi,+393489876543,m.bianchi@example.it,Torino
Anna,Verdi,+393331122334,anna.verdi@example.it,Bologna
Luca,Neri,+393201234567,l.neri@example.it,Milano

Fase 1 — Upload e anteprima

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/upload \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@clienti_nord_italia.csv" \
  -F "listId=87"

Response — File analizzato

{
  "uploadId": "upl-a1b2c3d4",
  "fileName": "clienti_nord_italia.csv",
  "totalRows": 5230,
  "parsedRows": 5230,
  "columns": ["nome", "cognome", "telefono", "email", "citta"],
  "preview": [
    {
      "nome": "Marco",
      "cognome": "Bianchi",
      "telefono": "+393489876543",
      "email": "m.bianchi@example.it",
      "citta": "Torino"
    },
    {
      "nome": "Anna",
      "cognome": "Verdi",
      "telefono": "+393331122334",
      "email": "anna.verdi@example.it",
      "citta": "Bologna"
    }
  ]
}

Fase 2 — Conferma mapping colonne

Mappa le colonne del CSV ai campi del sistema e conferma l'import:

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/mapped/file \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "uploadId": "upl-a1b2c3d4",
    "mapping": {
      "nome": "firstName",
      "cognome": "lastName",
      "telefono": "phoneNumber",
      "email": "email",
      "citta": "city"
    },
    "listId": 87
  }'

Response — Import completato

{
  "imported": 5104,
  "duplicates": 98,
  "invalid": 28,
  "listId": 87,
  "totalInList": 5105
}

Dietro le quinte — Processo di import CSV

Upload e parsing: Il file viene caricato e analizzato. Il sistema identifica le colonne e restituisce un'anteprima. Nessun contatto viene ancora creato.
Mapping e conferma: Tu confermi la mappatura delle colonne ai campi del sistema. Solo a questo punto i contatti vengono creati e associati alla lista.
Validazione numeri: I numeri vengono validati in formato internazionale. Numeri malformati o senza prefisso vengono scartati.
Deduplicazione: Contatti con lo stesso numero di telefono vengono conteggiati come duplicates e non inseriti di nuovo.

Questo approccio in due fasi previene errori: puoi verificare che le colonne siano mappate correttamente prima di committare migliaia di record.

Step 2c — Import da VCard

Per importare contatti da una rubrica telefonica in formato .vcf:

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/upload/vcard \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@rubrica_aziendale.vcf" \
  -F "listId=87"

Response — VCard analizzato

{
  "uploadId": "upl-e5f6g7h8",
  "fileName": "rubrica_aziendale.vcf",
  "totalContacts": 342,
  "parsedContacts": 339,
  "errors": 3
}

Conferma l'import VCard:

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/mapped/vcard \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "uploadId": "upl-e5f6g7h8",
    "listId": 87
  }'

{
  "imported": 335,
  "duplicates": 4,
  "invalid": 3,
  "listId": 87,
  "totalInList": 5440
}

:::info Mapping automatico VCard A differenza del CSV, i contatti VCard usano campi standard (FN, TEL, EMAIL, ADR) che vengono mappati automaticamente senza richiedere una configurazione manuale. :::

Step 3 — Verifica i contatti nella lista

Consulta i contatti presenti nella lista con paginazione.

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts/list/87/contacts?page=0&size=10" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Elenco contatti

{
  "content": [
    {
      "id": 24501,
      "firstName": "Giulia",
      "lastName": "Rossi",
      "phoneNumber": "+393401234567",
      "email": "giulia.rossi@example.it",
      "valid": true
    },
    {
      "id": 24502,
      "firstName": "Marco",
      "lastName": "Bianchi",
      "phoneNumber": "+393489876543",
      "email": "m.bianchi@example.it",
      "valid": true
    }
  ],
  "totalElements": 5440,
  "totalPages": 544,
  "page": 0,
  "size": 10
}

Step 4 — Usa la lista in una campagna

Passa il listId come contactListId nella configurazione della campagna:

curl -X PUT https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/1542 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sender": "ShopItalia",
    "text": "Offerta esclusiva per i clienti del Nord Italia! -30% su tutto con codice NORD30.",
    "contactListId": 87
  }'

Vedi UC-006 — Campagna SMS Bulk per il flusso completo di invio campagna.

Operazioni aggiuntive

Rimuovi contatti da una lista

curl -X DELETE 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 '{
    "contactIds": [24501],
    "listIds": [87]
  }'

{
  "removed": 1
}

Cerca contatti per filtro

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/contacts?city=Milano&page=0&size=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Riferimento rapido endpoint

Azione	Metodo	Endpoint
Lista contatti	`GET`	`/contacts`
Crea contatto	`POST`	`/contacts`
Aggiorna contatto	`PUT`	`/contacts/{id}`
Elimina contatti	`DELETE`	`/contacts`
Lista delle liste	`GET`	`/contacts/list`
Crea lista	`POST`	`/contacts/list`
Aggiungi a lista	`POST`	`/contacts/list/contacts`
Rimuovi da lista	`DELETE`	`/contacts/list/contacts`
Contatti in lista	`GET`	`/contacts/list/{id}/contacts`
Upload CSV	`POST`	`/contacts/upload`
Upload VCard	`POST`	`/contacts/upload/vcard`
Conferma CSV	`POST`	`/contacts/mapped/file`
Conferma VCard	`POST`	`/contacts/mapped/vcard`

Risultato atteso

Step	Azione	Risultato
1	`POST /contacts/list`	Lista creata con `id`
2a	`POST /contacts` + `POST /contacts/list/contacts`	Contatto creato e associato alla lista
2b	`POST /contacts/upload` + `POST /contacts/mapped/file`	5.104 contatti importati da CSV
2c	`POST /contacts/upload/vcard` + `POST /contacts/mapped/vcard`	335 contatti importati da VCard
3	`GET /contacts/list/{id}/contacts`	Elenco paginato dei contatti nella lista
4	`PUT /campaigns/{id}` con `contactListId`	Lista associata alla campagna

Prossimi passi

UC-006 — Campagna SMS Bulk: Usa le liste appena create per lanciare campagne
Guida Contatti e Liste: Approfondisci filtri, paginazione e gestione avanzata
Guida Export: Esporta i contatti per analisi esterne

Scenari reali​

Flusso di gestione contatti​

Step 1 — Crea una lista contatti​

Response — Lista creata​

Step 2a — Aggiungi contatti singolarmente​

Response — Contatto creato​

Step 2b — Import bulk da CSV​

Formato CSV atteso​

Fase 1 — Upload e anteprima​

Response — File analizzato​

Fase 2 — Conferma mapping colonne​

Response — Import completato​

Step 2c — Import da VCard​

Response — VCard analizzato​

Step 3 — Verifica i contatti nella lista​

Response — Elenco contatti​

Step 4 — Usa la lista in una campagna​

Operazioni aggiuntive​

Rimuovi contatti da una lista​

Cerca contatti per filtro​

Riferimento rapido endpoint​

Risultato atteso​

Prossimi passi​