Contact List

Organizza i contatti in liste denominate usate come obiettivi delle campagne.

📄️Cerca liste contatti

Restituisce un elenco paginato delle liste contatti del tuo account che corrispondono ai filtri forniti. Le liste contatti sono gruppi di contatti con un nome, che fungono da pubblico destinatario delle campagne. Un singolo contatto può appartenere a più liste. Usa il parametro search per trovare le liste per nome (corrispondenza parziale case-insensitive). Usa id (separati da virgola) per recuperare liste specifiche tramite i loro ID. Usa contactIds (separati da virgola) per trovare tutte le liste che contengono contatti specifici, utile per capire di quali liste è membro un contatto. Imposta isTest=true per recuperare solo le liste di test usate per inviare campagne di prova, oppure isTest=false per escluderle. Per impostazione predefinita, le liste eliminate sono escluse. Imposta includeDeleted=true per includere nei risultati le liste eliminate in modo logico (soft delete). I risultati sono paginati: page parte da 0, limit ha come valore predefinito 10 (massimo 1000). Usa sortBy per scegliere il campo di ordinamento (predefinito name) e sortOrder per asc o desc. Restituisce 500 in caso di errore imprevisto del server.

📄️Elimina liste contatti

Elimina una o più liste contatti tramite i loro ID. Fornisci il parametro ids come elenco di ID delle liste contatti da eliminare, separati da virgola. L'eliminazione di una lista contatti rimuove la lista e tutte le associazioni tra quella lista e i suoi contatti, ma non elimina i contatti stessi. I contatti restano nel tuo account e possono ancora appartenere ad altre liste. Se una lista eliminata è attualmente assegnata a una campagna in bozza o programmata, dovresti aggiornare quella campagna per rimuovere la lista eliminata dai suoi contactListIds prima di confermarla, altrimenti la validazione della campagna potrebbe non andare a buon fine. Questa operazione è irreversibile. Restituisce 200 con il risultato dell'operazione di eliminazione. Restituisce 500 in caso di errore imprevisto del server.

📄️Crea una nuova lista contatti

Crea una nuova lista contatti vuota nel tuo account. Una lista contatti è un gruppo con un nome che funge da pubblico destinatario delle campagne. Devi fornire almeno un nome per la lista. Dopo aver creato la lista, popolala aggiungendo contatti con POST /contacts/list/contacts (per i contatti esistenti) oppure importando contatti da un file con POST /contacts/upload o POST /contacts/upload/vcard (che possono assegnare automaticamente alla lista i contatti importati). Puoi poi assegnare la lista a una o più campagne includendo il suo ID nel campo contactListIds quando crei o aggiorni una campagna. Imposta il flag isTest su true se questa lista è destinata solo a scopi di test (es. inviare messaggi di prova a destinatari interni prima di lanciare una campagna reale). Restituisce 201 con i dettagli della lista contatti creata, incluso l'ID della lista generato. Restituisce 400 se nel corpo della richiesta mancano campi obbligatori o sono presenti dati non validi. Restituisce 500 in caso di errore imprevisto del server.

📄️Rimuovi contatti dalle liste contatti

Rimuove in blocco i contatti dalle liste contatti eliminando le loro associazioni. Il corpo della richiesta deve includere listIds (le liste contatti da cui rimuovere i contatti) e, a scelta, contactIds specifici oppure allContacts=true. Quando allContacts è false, fornisci contactIds come lista di ID contatto da rimuovere dalle liste specificate. In questa modalità il campo contactIds è obbligatorio. Quando allContacts è true, tutti i contatti vengono rimossi dalle liste specificate, tranne quelli i cui ID sono in excludeIdsAllContacts. Questa operazione rimuove solo le associazioni contatto-lista; non elimina né i contatti né le liste. I contatti rimossi da una lista non saranno più destinatari delle campagne rivolte a quella lista, a meno che non appartengano anche a un'altra lista usata dalla stessa campagna. Usala per ripulire le appartenenze alle liste, preparare le liste per una nuova importazione o restringere il pubblico di una campagna. Per eliminare una singola associazione tramite il suo ID, usa invece DELETE /contacts/list/contacts/{id}. Restituisce 200 con il risultato dell'operazione di dissociazione. Restituisce 400 se listIds è vuoto, oppure se allContacts è false e contactIds non è fornito. Restituisce 500 in caso di errore imprevisto del server.

📄️Aggiungi contatti alle liste contatti

Crea associazioni tra contatti e liste contatti, aggiungendo di fatto i contatti come membri delle liste specificate. Il corpo della richiesta deve includere listIds (le liste contatti di destinazione) e, a scelta, contactIds specifici oppure allContacts=true. Quando allContacts è false, fornisci contactIds come lista di ID contatto da aggiungere alle liste specificate. Quando allContacts è true, tutti i contatti del tuo account vengono aggiunti alle liste specificate, tranne quelli i cui ID sono in excludeIdsAllContacts. Si tratta di un'operazione in blocco: puoi aggiungere più contatti a più liste in una singola chiamata. Se un contatto è già membro di una determinata lista, l'associazione esistente viene mantenuta (non viene creato alcun duplicato). Dopo aver aggiunto i contatti alle liste, le liste aggiornate possono essere usate come pubblico delle campagne includendole nei contactListIds di una campagna. Restituisce 201 con gli ID delle associazioni create. Restituisce 400 se listIds è vuoto o se il corpo della richiesta non è valido per altri motivi. Restituisce 500 in caso di errore imprevisto del server.

📄️Elimina associazione per ID

Elimina una singola associazione tra un contatto e una lista contatti, identificata dall'ID numerico dell'associazione. Questo rimuove il contatto dalla lista ma non elimina né il contatto né la lista. L'ID associazione è un identificatore univoco del collegamento tra un contatto specifico e una lista specifica. Puoi ottenere gli ID associazione dalla risposta di POST /contacts/list/contacts al momento della creazione delle associazioni. Per rimuovere in blocco contatti dalle liste, usa invece DELETE /contacts/list/contacts/, che supporta la rimozione di più contatti contemporaneamente. Restituisce 200 in caso di eliminazione riuscita dell'associazione. Restituisce 404 se non esiste alcuna associazione con l'ID specificato nel tuo account. Restituisce 500 in caso di errore imprevisto del server.

📄️Aggiorna una lista contatti

Aggiorna i metadati di una lista contatti esistente identificata dal suo ID numerico. Puoi modificare il nome della lista, la descrizione e il flag isTest. Questo endpoint aggiorna solo i metadati della lista; non aggiunge né rimuove contatti dalla lista. Per aggiungere o rimuovere contatti, usa rispettivamente POST /contacts/list/contacts e DELETE /contacts/list/contacts/. Se la lista è attualmente assegnata a una campagna, la campagna userà automaticamente i metadati aggiornati della lista. Restituisce 200 con i dettagli della lista contatti aggiornata. Restituisce 400 se il corpo della richiesta contiene dati non validi. Restituisce 404 se non esiste alcuna lista contatti con l'ID specificato nel tuo account. Restituisce 500 in caso di errore imprevisto del server.

📄️Ottieni lista contatti per ID

Recupera i dettagli completi di una singola lista contatti tramite il suo ID numerico. La risposta include il nome della lista, la descrizione, la data di creazione, il numero di contatti e se è contrassegnata come lista di test. Usa questo endpoint per esaminare una lista prima di assegnarla a una campagna tramite POST /campaigns o PUT /campaigns/{id}. Per recuperare i contatti effettivi di questa lista, usa GET /contacts/list/{listId}/contacts. Restituisce 404 se non esiste alcuna lista contatti con l'ID specificato nel tuo account. Restituisce 500 in caso di errore imprevisto del server.

📄️Cerca contatti in una lista contatti

Restituisce i contatti che appartengono a una specifica lista contatti, con filtri opzionali e paginazione. È un endpoint di comodità equivalente a chiamare GET /contacts con il parametro listIds impostato sul listId indicato. Sono disponibili tutti gli stessi filtri a livello di contatto: search (corrispondenza testuale case-insensitive sul nome), gender, isValid (contatto raggiungibile su almeno uno tra telefono ed email), communicationSupported (es. SMS, RCS, WHATSAPP), isTest, phoneNumber, email, lastContactType e lastCampaignType. I risultati sono paginati: page parte da 0, limit ha come valore predefinito 10 (massimo 1000). Usa sortBy per scegliere il campo di ordinamento (predefinito fullName) e sortOrder per asc o desc. Usa questo endpoint per visualizzare in anteprima il pubblico di una lista contatti prima di assegnarla a una campagna, o per verificare quali contatti sono stati importati dopo il caricamento di un file. Restituisce 404 se non esiste alcuna lista contatti con il listId specificato nel tuo account. Restituisce 500 in caso di errore imprevisto del server.