Contact

Gestisci i singoli contatti nella tua rubrica.

📄️Cerca contatti

Cerca e recupera i contatti con filtri flessibili e paginazione. Questo endpoint ha due comportamenti distinti a seconda del parametro listIds. Quando listIds è fornito (ID di liste contatti separati da virgola), restituisce l'insieme distinto dei contatti che appartengono a quelle liste, con eventuali filtri aggiuntivi applicati in più. Quando listIds è omesso, cerca tra tutti i contatti del tuo account che corrispondono ai filtri forniti. Usa notListIds per escludere i contatti che appartengono a liste specifiche, utile per trovare i contatti non ancora assegnati a una lista di destinazione. Il parametro search esegue una corrispondenza case-insensitive sul nome del contatto e su altri campi di testo. Puoi filtrare per gender, isValid (contatto raggiungibile su almeno uno tra telefono ed email), communicationSupported (es. SMS, RCS, WHATSAPP), isTest (per trovare o escludere i contatti di test), phoneNumber (corrispondenza esatta) ed email (corrispondenza esatta). 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. Il parametro sortPriorityListId fa apparire per primi nei risultati i contatti che appartengono a quella specifica lista, utile quando visualizzi i contatti con una lista principale evidenziata. Per recuperare i contatti di una lista specifica con un'API più semplice, valuta invece GET /contacts/list/{listId}/contacts. Restituisce 500 in caso di errore imprevisto del server.

📄️Elimina contatti

Elimina contatti dal tuo account. Questo endpoint supporta due modalità che si escludono a vicenda. Modalità 1 (eliminazione selettiva): fornisci ids come lista di ID contatto separati da virgola per eliminare contatti specifici. Quando ids è presente, il parametro notIds viene ignorato. Modalità 2 (eliminazione massiva con esclusioni): fornisci notIds come lista di ID contatto separati da virgola da mantenere, e tutti gli altri contatti del tuo account verranno eliminati. Questa operazione rimuove definitivamente i record dei contatti e rimuove anche le loro associazioni con qualsiasi lista contatti. I contatti eliminati non saranno più disponibili come destinatari per le campagne future. Lo storico di consegna delle campagne passate che includevano questi contatti viene conservato. Usalo con cautela, specialmente la Modalità 2, perché può eliminare un gran numero di contatti in una singola chiamata. Restituisce 200 con il risultato dell'operazione di eliminazione. Restituisce 500 in caso di errore imprevisto del server.

📄️Crea un nuovo contatto

Crea un nuovo contatto individuale nel tuo account. Devi fornire almeno un numero di telefono o un indirizzo email. Il numero di telefono dovrebbe essere in formato internazionale E.164 (es. +393331234567). Puoi includere campi opzionali come firstName, lastName, gender e qualsiasi campo personalizzato configurato nel tuo account. Dopo aver creato un contatto, puoi assegnarlo a una o più liste contatti usando POST /contacts/list/contacts, in modo che diventi un destinatario delle campagne. Per le importazioni massive, usa POST /contacts/upload (CSV/Excel) o POST /contacts/upload/vcard (VCF) invece di creare i contatti uno per uno. Restituisce 201 con i dettagli del contatto creato, incluso l'ID contatto generato. Restituisce 400 se nel corpo della richiesta mancano campi obbligatori o sono presenti dati non validi (es. numero di telefono malformato). Restituisce 500 in caso di errore imprevisto del server.

📄️Carica e analizza un file lista contatti

Carica un file tabellare e importa le sue righe come contatti nel tuo account. I formati di file supportati includono CSV (.csv), Microsoft Excel (.xls, .xlsx) e altri file di testo delimitati. Il formato del file viene rilevato dall'estensione di fileName. Il file deve essere inviato come multipart/form-data, con il file nel campo 'file' e il nome originale del file nel campo 'fileName'. Imposta removeHead=true se la prima riga del file contiene intestazioni di colonna che non devono essere importate come record contatto. Il parametro limit controlla quante righe analizzate vengono restituite nell'anteprima della risposta (predefinito 10), ma non limita il numero effettivo di contatti importati. L'importazione viene eseguita in modalità CREATE_UPDATE: i nuovi contatti vengono creati e i contatti esistenti (individuati tramite numero di telefono) vengono aggiornati con i nuovi dati. Se viene fornito un listId, tutti i contatti importati correttamente vengono aggiunti automaticamente a quella lista contatti. La mappatura delle colonne viene eseguita automaticamente in base ai nomi di intestazione riconosciuti (es. firstName, lastName, phoneNumber, email). Restituisce 400 se il tipo di file non è supportato, se il file è danneggiato o se non può essere analizzato. Restituisce 500 se si verifica un errore imprevisto del server durante l'elaborazione dell'importazione.

📄️Carica e analizza un file VCard

Carica un file VCard (.vcf) e importa le sue voci come contatti nel tuo account. Il file deve essere inviato come multipart/form-data, con il file nel campo 'file' e il nome originale del file (deve avere estensione .vcf) nel campo 'fileName'. I file VCard possono contenere una o più voci di contatto. Ogni voce vCard viene analizzata e mappata a un record contatto usando i campi vCard standard (FN, TEL, EMAIL, ecc.). L'importazione viene eseguita in modalità CREATE_UPDATE: i nuovi contatti vengono creati e i contatti esistenti (individuati tramite numero di telefono) vengono aggiornati con i dati della VCard. Se viene fornito un listId, tutti i contatti importati correttamente vengono aggiunti automaticamente a quella lista contatti. Il parametro limit controlla quanti contatti analizzati vengono restituiti nell'anteprima della risposta (predefinito 10), ma non limita il numero effettivo di contatti importati. Questo endpoint è particolarmente utile per importare contatti esportati da rubriche telefoniche, Outlook, Google Contacts o altri strumenti CRM che supportano lo standard VCard. Restituisce 400 se il file non ha estensione .vcf o non è un file VCard valido. Restituisce 500 se si verifica un errore imprevisto del server durante l'elaborazione dell'importazione.

📄️Aggiorna un contatto

Aggiorna un contatto esistente identificato dal suo ID numerico. Puoi modificare qualsiasi campo del contatto: nome, numero di telefono, email, genere, campi personalizzati, ecc. Vengono aggiornati solo i campi forniti nel corpo della richiesta; i campi omessi restano invariati. Usa prima GET /contacts/{id} per recuperare i valori attuali, se devi eseguire un aggiornamento parziale e vuoi preservare i dati esistenti. L'aggiornamento del numero di telefono di un contatto può influire sul suo stato di validità e sulle sue capacità di comunicazione (es. un nuovo numero potrebbe non supportare RCS). Le appartenenze alle liste contatti non sono influenzate da questo endpoint; usa gli endpoint /contacts/list/contacts per gestire le associazioni alle liste. Restituisce 200 con i dettagli del contatto aggiornato. Restituisce 400 se il corpo della richiesta contiene dati non validi. Restituisce 404 se non esiste alcun contatto con l'ID specificato nel tuo account. Restituisce 500 in caso di errore imprevisto del server.

📄️Ottieni contatto per ID

Recupera i dettagli completi di un singolo contatto tramite il suo ID numerico. La risposta include tutti i campi memorizzati: nome, numero di telefono, email, genere, stato di validità, capacità di comunicazione, campi personalizzati ed eventuali appartenenze a liste contatti. Usa questo endpoint per esaminare il record di un contatto prima di aggiornarlo con PUT /contacts/{id}, o per verificare i dettagli di un contatto dopo la creazione. Restituisce 404 se non esiste alcun contatto con l'ID specificato nel tuo account. Restituisce 500 in caso di errore imprevisto del server.