Campaigns

Crea, programma e monitora campagne di messaggistica massiva.

📄️Elenca campagne

Restituisce un elenco paginato delle campagne del tuo account. Usa isDraft=true per vedere le bozze non pubblicate che non sono ancora state confermate, oppure isDraft=false per escluderle. Usa isProgrammed=true per ottenere solo le campagne che sono state confermate e programmate per un invio futuro. Filtra per canale con sendingMode impostato su SMS, RCS o WHATSAPP (sono accettati valori separati da virgola per corrispondere a più canali contemporaneamente). Il parametro search esegue una corrispondenza case-insensitive sui campi nome e descrizione della campagna. Usa startDate e endDate (formato yyyy-MM-dd) insieme per limitare i risultati alle campagne create o programmate entro quell'intervallo di date. I risultati sono paginati: page parte da 0 e limit controlla la dimensione della pagina. Usa direction=ASC o direction=DESC per controllare l'ordinamento. Il filtro readyToSend ti permette di trovare le campagne completamente configurate ma non ancora confermate (true) o le campagne ancora in fase di bozza (false). Questo endpoint è utile per costruire dashboard delle campagne e monitorare lo stato complessivo delle tue operazioni di messaggistica. Restituisce 401 se la chiave API è mancante o non valida.

📄️Crea una campagna

Crea una nuova campagna di messaggistica massiva. Il ciclo di vita tipico è: (1) Crea la campagna con readyToSend=false per salvarla come bozza. (2) Facoltativamente, aggiorna la campagna con PUT /campaigns/{id} per modificarne la configurazione. (3) Chiama POST /campaigns/{id}/calculateGoal per calcolare il numero di destinatari e il costo stimato. (4) Verifica il prezzo con GET /campaigns/{id}/price. (5) Imposta readyToSend=true tramite PUT /campaigns/{id} quando la configurazione è definitiva. (6) Conferma e invia la campagna con PUT /campaigns/{id}/confirm. Il canale è determinato dal campo sendingMode. I valori validi sono: SMS (messaggi di solo testo), RCS (messaggi rich card tramite un agente RCS), WHATSAPP (template WhatsApp pre-approvati) e modalità combinate come RCS_SMS, WHATSAPP_SMS, WHATSAPP_RCS, WHATSAPP_RCS_SMS, che forniscono il fallback automatico tra i canali. Per le campagne SMS devi fornire smsSender (l'ID mittente alfanumerico o il numero di telefono) e smsBody (il testo del messaggio, che supporta la sintassi {{placeholder}} per la personalizzazione con i campi del contatto). Per le campagne RCS devi fornire rcsAgentId e rcsTemplateId. Per le campagne WhatsApp devi fornire whatsappPhoneNumberId e whatsappTemplateId. I destinatari vengono specificati tramite contactListIds (un array di ID di liste contatti, destinationType=1) oppure tramite destinations (un array di numeri di telefono in formato E.164, destinationType=2). Puoi impostare una scheduledDate futura (formato: yyyy-MM-dd HH:mm:ss.SSSZ) per programmare la campagna per un invio successivo anziché per l'invio immediato al momento della conferma. Restituisce 400 se mancano campi obbligatori o se sendingMode non è un valore valido. Restituisce 401 se la chiave API è mancante o non valida.

📄️Ottieni statistiche della campagna

Restituisce statistiche di consegna aggregate per le campagne in un dato intervallo di date. I risultati sono raggruppati in base all'intervallo temporale aggregateOn. I valori validi per aggregateOn sono: hour, day, week e month. Devi fornire sia startDate sia endDate in formato yyyy-MM-dd per definire il periodo del report. Filtra per sendingMode (SMS, RCS, WHATSAPP) per vedere le statistiche di un canale specifico, oppure omettilo per ottenere statistiche combinate su tutti i canali. Imposta isDraft=false per escludere le campagne in bozza mai inviate, in modo che solo le campagne confermate e inviate contribuiscano alle statistiche. Ogni intervallo temporale nella risposta contiene i conteggi dei messaggi totali inviati, consegnati, non riusciti e di altre metriche di consegna. I risultati sono paginati: usa page (a partire da 0) e limit per controllare la paginazione, e direction=ASC o direction=DESC per ordinare gli intervalli temporali in ordine cronologico o inverso. Questo endpoint è utile per costruire dashboard di analisi, generare report di consegna periodici e monitorare l'andamento delle performance delle campagne nel tempo. Restituisce 401 se la chiave API è mancante o non valida.

📄️Aggiorna una campagna

Aggiorna i dettagli di una campagna esistente. Solo le campagne ancora in stato bozza (status=0) o programmata (status=1) possono essere modificate. Le campagne attualmente in fase di invio (status=2), completate (status=3) o fallite (status=4) non possono essere aggiornate. Puoi usare questo endpoint per modificare nome, descrizione, corpo del messaggio, mittente, liste contatti dei destinatari, modalità di invio, data programmata o il flag readyToSend della campagna. Un flusso di lavoro comune consiste nel creare una campagna come bozza (readyToSend=false), perfezionarne la configurazione con questo endpoint, poi impostare readyToSend=true quando la campagna è finalizzata e infine chiamare PUT /campaigns/{id}/confirm per inviarla. Dopo aver aggiornato le liste dei destinatari o il contenuto del messaggio, chiama POST /campaigns/{id}/calculateGoal per aggiornare il numero di destinatari e la stima dei costi. Restituisce 400 se il corpo della richiesta non è valido o se la campagna è in uno stato non modificabile. Restituisce 404 se non esiste alcuna campagna con l'ID specificato nel tuo account. Restituisce 401 se la chiave API è mancante o non valida.

📄️Ottieni una campagna

Restituisce i dettagli completi di una singola campagna identificata dal suo ID numerico. La risposta include lo stato della campagna, il canale di invio (sendingMode), il numero di destinatari (totalDestinations), i risultati di consegna (totalSuccess, totalFailed), il contenuto del messaggio (smsBody per SMS, ID dei template per RCS o WhatsApp), la lista dei contactListIds associati e l'eventuale data programmata. Usa questo endpoint per esaminare una campagna in qualsiasi fase del suo ciclo di vita: in bozza, dopo la conferma, durante l'invio o dopo il completamento. Il campo status è numerico: 0 significa bozza, 1 significa pronta/programmata, 2 significa invio in corso, 3 significa completata e 4 significa fallita. Restituisce 404 se non esiste alcuna campagna con l'ID specificato nel tuo account. Restituisce 401 se la chiave API è mancante o non valida.

📄️Elimina una campagna

Elimina definitivamente una campagna. Solo le campagne ancora in stato bozza (status=0) o programmata (status=1) possono essere eliminate. Le campagne attualmente in fase di invio (status=2), già completate (status=3) o in stato di errore (status=4) non possono essere eliminate, perché i loro record di consegna devono essere conservati per la reportistica. Se devi fermare una campagna programmata prima che venga inviata, eliminala prima che venga raggiunta la scheduledDate. Questa operazione è irreversibile: una volta eliminata, la campagna e la sua configurazione vengono rimosse definitivamente e non possono essere recuperate. Restituisce 204 No Content in caso di eliminazione riuscita. Restituisce 404 se non esiste alcuna campagna con l'ID specificato nel tuo account, o se la campagna è in uno stato non eliminabile. Restituisce 401 se la chiave API è mancante o non valida.

📄️Ricalcola il costo della campagna

Ricalcola il numero stimato di destinatari e il costo totale della campagna in base alla sua configurazione attuale e alle liste contatti associate. Dovresti chiamare questo endpoint ogni volta che modifichi i destinatari della campagna (contactListIds o destinations) o cambi il sendingMode, perché canali diversi hanno prezzi per messaggio diversi e il numero di destinatari può cambiare se vengono aggiunte o rimosse liste. La risposta include l'oggetto campagna aggiornato con totalDestinations e i campi del costo ricalcolati. Questo è un passaggio preliminare necessario prima di confermare una campagna: se lo salti, l'endpoint di conferma potrebbe rifiutare la campagna perché il costo non è stato calcolato. Dopo averlo chiamato, usa GET /campaigns/{id}/price per ottenere solo il dettaglio del prezzo. Restituisce 404 se non esiste alcuna campagna con l'ID specificato nel tuo account. Restituisce 401 se la chiave API è mancante o non valida.

📄️Conferma / programma una campagna

Valida e conferma la campagna per l'invio. Questo è il passaggio finale e irreversibile del ciclo di vita della campagna: una volta confermata, i messaggi verranno inviati a tutti i destinatari (immediatamente o alla scheduledDate, se ne è stata impostata una). Prima di chiamare questo endpoint, assicurati che: (1) La campagna abbia un sendingMode valido e che i campi specifici del canale corrispondente siano compilati (smsSender/smsBody per SMS, rcsAgentId/rcsTemplateId per RCS, whatsappPhoneNumberId/whatsappTemplateId per WhatsApp). (2) Sia configurata almeno una fonte di destinatari (contactListIds o destinations). (3) Il costo della campagna sia stato calcolato chiamando POST /campaigns/{id}/calculateGoal. (4) Il tuo account abbia credito sufficiente a coprire il costo totale. (5) Il flag readyToSend sia impostato su true nella campagna. Restituisce 202 Accepted quando la campagna viene confermata con successo e messa in coda per la consegna. Restituisce 400 se una qualsiasi validazione non va a buon fine: campi obbligatori mancanti, saldo crediti insufficiente, readyToSend è false o il costo non è stato calcolato. Restituisce 404 se non esiste alcuna campagna con l'ID specificato nel tuo account. Restituisce 401 se la chiave API è mancante o non valida.

📄️Ottieni il prezzo totale della campagna

Restituisce il prezzo totale stimato della campagna in base alla sua configurazione attuale. Il prezzo dipende dal sendingMode (canale), dal numero di destinatari nelle liste contatti associate e dalla tariffa per messaggio del tuo account. Dovresti chiamare POST /campaigns/{id}/calculateGoal prima di usare questo endpoint, per assicurarti che la stima dei costi sia aggiornata. Se il costo non è ancora stato calcolato, il prezzo restituito potrebbe essere zero o non aggiornato. Usa questo endpoint per mostrare agli utenti un'anteprima del costo prima che confermino e inviino la campagna con PUT /campaigns/{id}/confirm. Restituisce 404 se non esiste alcuna campagna con l'ID specificato nel tuo account. Restituisce 401 se la chiave API è mancante o non valida.