Inviare un messaggio a contenuto remoto

Cosa sono i messaggi a contenuto remoto?

I messaggi a contenuto remoto rispondono alla necessità di veicolare tramite IO comunicazioni contenenti dati personali e/o dati sensibili dei cittadini, garantendone una gestione conforme alle normative sulla privacy. Infatti, scegliendo questa modalità di invio le informazioni non vengono memorizzate su IO, ma recuperate dai tuoi sistemi ogni volta che l'utente accede al messaggio in app.

Per un messaggio, i contenuti remotizzabili sono:

titolo;
corpo;
precondizioni di apertura (opzionali, es.: disclaimer);
allegati (Premium).

Cosa cambia?

📐 Architettura

A differenza dell'invio tradizionale, in cui è prevista la trasmissione dei contenuti del messaggio ai sistemi di IO, i messaggi remoti prevedono che tali contenuti risiedano esclusivamente presso i tuoi sistemi e sarà IO a recuperarli ogni volta che l'utente destinatario vorrà visualizzarli in app.

In questo modo, IO fa da canale di comunicazione in tempo reale tra te e il tuo utente e detiene unicamente le informazioni necessarie per consentire il recupero del messaggio e verificarne lo stato.

La gestione dei messaggi remotizzati implica che la tua organizzazione è responsabile dei contenuti veicolati tramite IO, con particolare riferimento alla loro accuratezza e disponibilità verso l'utente.

🕵️‍♂️ Gestione delle informazioni sensibili

Come specificato, i messaggi remotizzati sono pensati per garantire un invio privacy compliant di informazioni personali/sensibili riferite al destinatario, ove necessarie per l’erogazione del servizio.

Ti ricordiamo che tale modalità d'invio lascia invariati i tuoi obblighi ai sensi della normativa vigente, in particolare ai sensi dell'art. 7.3 delle Linee Guida IO.

Come ulteriore misura a protezione della privacy, il flag require_secure_channels ti consente di marcare un messaggio come contenente informazioni sensibili, con i seguenti effetti:

le notifiche push sui dispositivi del destinatario mostreranno un generico invito ad aprire il messaggio, senza riportare il contenuto del titolo;
i messaggi non verranno inoltrati via email a prescindere dalla preferenza impostata dall'utente destinatario.

Puoi anche impostare il flag require_secure_channels direttamente sul servizio, così non devi preoccuparti di farlo per ogni singolo messaggio.

✏️ Aggiornamento dei contenuti nel tempo

A differenza dei messaggi tradizionali, i messaggi a contenuto remoto possono essere modificati anche dopo l'invio: potrai ad esempio correggere un refuso, o aggiornare dinamicamente informazioni non più valide o fuorvianti (es.: a seguito della cancellazione di un appuntamento).

Nel considerare tale possibilità, è bene ricordare che:

L'utente destinatario non riceverà alcun avviso in caso di aggiornamento del contenuto di un messaggio precedentemente ricevuto. Infatti, il contenuto può essere riattualizzato, richiamandolo dai tuoi sistemi, solo quando e se l'utente apre il messaggio in app;
La responsabilità delle informazioni trasmesse tramite IO rimane in ogni caso in capo all'ente mittente.

In linea di principio, quando il contesto che ha prodotto un messaggio cambia o devono essere trasmesse nuove informazioni, è sempre preferibile inviare un nuovo messaggio per informare il destinatario.

In caso di dubbi, prediligi sempre il mantenimento della coerenza informativa nei confronti della tua utenza: i messaggi su IO sono un importante biglietto da visita per la tua organizzazione, assicurane la qualità!

Caso d'uso prenotazione appuntamento - Esempio di aggiornamento dei contenuti di un messaggio dopo l'invio

Il tuo ente invia al cittadino destinatario un messaggio a contenuto remoto per confermare l'avvenuta prenotazione di un appuntamento per una prestazione sanitaria:
Il destinatario legge il messaggio e decide di disdire l'appuntamento tramite i canali da te messi a disposizione per la gestione delle prenotazioni;
Il tuo ente invia allo stesso utente un nuovo messaggio per confermare l'annullamento;
Per assicurare la coerenza informativa, il tuo ente aggiorna i contenuti del primo messaggio sostituendo e/o eliminando le informazioni di conferma appuntamento e i riferimenti obsoleti.

Per dare contezza al destinatario del fatto che i contenuti potrebbero essere aggiornati nel tempo, in calce al dettaglio di tutti i messaggi con contenuto remoto è stato incluso il seguente avviso, nella sua versione breve ed estesa:

IO non effettua alcun controllo sull'invariabilità nel tempo dei contenuti di un messaggio a contenuto remoto. L'accuratezza e la disponibilità delle informazioni contenute nel messaggio sono sempre di responsabilità esclusiva dell'Ente mittente.

In qualità di titolare del trattamento, dovrai garantire direttamente agli utenti l'esercizio dei diritti degli interessati ai sensi del GDPR, e ogni richiesta in tal senso verrà reindirizzata a te. Ad esempio, il diritto di accesso ai sensi dell'art. 15 GDPR dovrà essere garantito agli interessati che ne fanno richiesta, anche tramite i recapiti presenti nella scheda servizio.

Come funziona l’invio di un messaggio a contenuto remoto?

Prima di poter inviare messaggi a contenuto remoto è necessario seguire la procedura illustrata in Condivisione configurazione remota

Il ciclo di vita di un messaggio a contenuto remoto si compone di due momenti principali:

L'invio (creazione) da parte dei sistemi della tua organizzazione;
La fruizione (visualizzazione) da parte del destinatario.

Entrambe le fasi richiedono un'integrazione tra i tuoi sistemi e quelli di IO.

Fase di invio del messaggio

Creazione del messaggio a contenuto remoto

In questa fase, sono i tuoi sistemi integrati con IO a richiedere la creazione (e quindi l'invio) di un nuovo messaggio a uno specifico destinatario. Per maggiori informazioni sull'invio di un messaggio su IO fai riferimento a Inviare un messaggio.

La tabella che segue riepiloga le principali componenti remotizzabili di un messaggio IO:

Componente	Note
precondizioni	Si tratta di informazioni opzionali, che vengono mostrate prima dell'apertura del dettaglio del messaggio.
titolo (subject)	Si tratta del titolo visibile all'apertura del messaggio, che differisce da quello visibile nella lista messaggi (non remotizzabile).
corpo (markdown)	Si tratta del contenuto testuale del messaggio.
dettagli di un avviso di pagamento	Sono già remotizzati grazie all'integrazione con il nodo pagoPA.
allegati (PDF)	Sono contenuti gestibili solo in remoto. Puoi inserirli se hai sottoscritto l'Accordo Premium. Il formato accettato è PDF.

Componente

Note

precondizioni

Si tratta di informazioni opzionali, che vengono mostrate prima dell'apertura del dettaglio del messaggio.

titolo (subject)

Si tratta del titolo visibile all'apertura del messaggio, che differisce da quello visibile nella lista messaggi (non remotizzabile).

corpo (markdown)

Si tratta del contenuto testuale del messaggio.

dettagli di un avviso di pagamento

Sono già remotizzati grazie all'integrazione con il nodo pagoPA.

allegati (PDF)

Sono contenuti gestibili solo in remoto. Puoi inserirli se hai sottoscritto l'Accordo Premium. Il formato accettato è PDF.

Informazioni importanti circa le precondizioni all'apertura del messaggio

Come ente mittente, puoi decidere che l’apertura del messaggio debba essere preceduta da un contenuto mirato ad informare il destinatario circa aspetti o circostanze particolari relative al messaggio stesso.

Le precondizioni sono una schermata intermedia tra l'elenco dei messaggi e il dettaglio del messaggio selezionato. L’utente accede al dettaglio del messaggio solo se seleziona il bottone "Continua".

Di fatto, la visualizzazione delle precondizioni porta a un’interruzione del flusso di lettura di un messaggio. Quindi, è bene utilizzarle solo negli scenari in cui portino effettivamente valore alla tua comunicazione o siano altrimenti richiesti dalla normativa vigente, al fine di non degradare l'esperienza utente.

Quando usarle: Quando è necessario attirare l’attenzione del cittadino su un’informazione fondamentale, e in ogni caso quando richiesto dalla normativa applicabile, ad esempio nelle comunicazioni a valore legale per cui l’apertura del messaggio produce effetti nella sfera giuridica del cittadino.

Quando non usarle: Per trasmettere avvisi non strettamente correlati al contenuto del messaggio o per aggiungere informazioni di dettaglio che possono essere fornite al suo interno o in altri momenti dell’esperienza utente.

Informazioni importanti circa il titolo (subject) del messaggio

Il titolo del messaggio è usato da app IO in tre occasioni:

come titolo visibile in elenco messaggi ricevuti;
come intestazione del dettaglio del messaggio, una volta aperto;
nel testo delle notifiche push collegate al messaggio (ove abilitate dall'utente e ove il messaggio / servizio non siano da te contrassegnati come veicolanti informazioni sensibili)

A seconda del valore del flag has_remote_content che specificherai in third_party_data (vedi più avanti in questo capitolo) il titolo del messaggio presenterà comportamenti differenti:

se has_remote_content=true, il campo subject * indicato al momento della creazione del messaggio è usato da IO solo nell'elenco dei messaggi ricevuti. L'intestazione visibile all'interno del dettaglio del messaggio è invece recuperata successivamente (vedi #cosa-succede-quando-il-destinatario-apre-un-messaggio-remotizzato). Questo significa che i due campi potrebbero differire. Consigliamo di non modificare il titolo in modo sostanziale, in modo da mantenere la coerenza informativa tra i due testi. Inoltre, ti ricordiamo che ai sensi delle Linee Guida IO, non è possibile inserire informazioni sensibili nel titolo del messaggio.

se has_remote_content=false oppure se non includi il flag, il campo subject * presenta il funzionamento standard di un messaggio tradizionale (non remoto): lo stesso contenuto testuale è usato in elenco messaggi e nel dettaglio del messaggio.

Informazioni importanti circa il corpo (markdown) del messaggio

In fase di creazione di un messaggio a contenuto remoto, è comunque necessario, nel rispetto dell’interfaccia API di IO, definire un testo (markdown) “di cortesia” non remotizzato, che verrà utilizzato per comporre l’email di inoltro messaggio che gli utenti di IO possono scegliere di ricevere quando gli viene recapitato un messaggio in app.

Limiti markdown ai fini dell’inoltro: min 80, max 134 caratteri, oltre il sistema tronca con puntini di sospensione.

Nota sull'inoltro dei messaggi via email: Se abilitato dall'utente finale, un messaggio inviato tramite IO può essere inoltrato al suo indirizzo email. L'email contiene l'incipit del corpo del messaggio (i primi 134 caratteri), nonché un invito ad aprire l'app per accedere al contenuto completo tramite CTA che consente il redirect. Ecco un esempio di email di inoltro:

Nota sugli allegati (Premium) Se hai sottoscritto l’Accordo Premium, i tuoi messaggi potranno includere anche allegati in formato PDF: anch'essi saranno quindi trasmessi direttamente dai tuoi sistemi all’app quando il destinatario apre il messaggio. Per maggiori informazioni fai riferimento a Aggiungere allegati

Per i messaggi a contenuto remoto, è obbligatorio inserire le seguenti informazioni aggiuntive nel blocco third_party_data:

Campo Descrizione campo

Campo	Descrizione campo
id *	Questo è l'identificativo di correlazione remota, che identifica univocamente uno specifico messaggio indirizzato a uno specifico destinatario. Tale identificativo, determinato da te, consiste in una stringa che consente alle API di recuperare i contenuti remoti per tale specifico messaggio.
has_precondition	Imposta questo campo solo se vorrai che, al momento dell' apertura del messaggio in app, al destinatario sia mostrato un testo (con relativo titolo) recante informazioni di contesto che indicherai in quel momento (per maggiori informazioni fai riferimento a Endpoint di recupero delle precondizioni all'apertura del messaggio): letto il testo, il destinatario potrà scegliere se continuare con l'apertura del messaggio o se tornare alla lista dei messaggi ricevuti; i valori possibili per questo campo sono: `NEVER` (default) `ONCE` (le precondizioni sono mostrate solo la prima volta che il destinatario cerca di aprire il messaggio) `ALWAYS` (le precondizioni sono mostrate tutte le volte, anche se il messaggio era stato già letto in precedenza)
has_remote_content	Imposta il campo col valore `true` se vuoi che il titolo (soggetto) e il corpo del messaggio siano remotizzati; quando IO te li richiederà tramite l'apposita API che avrai esposto, dovrai rispondere con una stringa di testo per il titolo e un markdown per il corpo, come li avresti specificati in fase di creazione di un messaggio tradizionale; il default per questo campo è il valore `false`. Per maggiori informazioni e per comprendere il ruolo del titolo in un messaggio con contenuto remoto fai riferimento a Endpoint di recupero dei dettagli del messaggio
has_attachments	Imposta il campo col il valore `true` se al messaggio vuoi che siano allegati uno o più documenti in formato PDF: come illustrato in Endpoint di recupero dei dettagli del messaggio, quando IO ti richiederà i dettagli del messaggio dovrai indicare i metadati degli allegati (nome e relativa URL); quando il destinatario selezionerà un allegato in app, IO recupererà i byte presso i tuoi sistemi, tramite l'apposita API descritta in Endpoint di recupero dei byte del singolo allegato.

id *

Questo è l'identificativo di correlazione remota, che identifica univocamente uno specifico messaggio indirizzato a uno specifico destinatario. Tale identificativo, determinato da te, consiste in una stringa che consente alle API di recuperare i contenuti remoti per tale specifico messaggio.

has_precondition

Imposta questo campo solo se vorrai che, al momento dell' apertura del messaggio in app, al destinatario sia mostrato un testo (con relativo titolo) recante informazioni di contesto che indicherai in quel momento (per maggiori informazioni fai riferimento a Endpoint di recupero delle precondizioni all'apertura del messaggio): letto il testo, il destinatario potrà scegliere se continuare con l'apertura del messaggio o se tornare alla lista dei messaggi ricevuti; i valori possibili per questo campo sono:

NEVER (default)
ONCE (le precondizioni sono mostrate solo la prima volta che il destinatario cerca di aprire il messaggio)
ALWAYS (le precondizioni sono mostrate tutte le volte, anche se il messaggio era stato già letto in precedenza)

has_remote_content

Imposta il campo col valore true se vuoi che il titolo (soggetto) e il corpo del messaggio siano remotizzati; quando IO te li richiederà tramite l'apposita API che avrai esposto, dovrai rispondere con una stringa di testo per il titolo e un markdown per il corpo, come li avresti specificati in fase di creazione di un messaggio tradizionale; il default per questo campo è il valore false. Per maggiori informazioni e per comprendere il ruolo del titolo in un messaggio con contenuto remoto fai riferimento a Endpoint di recupero dei dettagli del messaggio

has_attachments

Imposta il campo col il valore true se al messaggio vuoi che siano allegati uno o più documenti in formato PDF: come illustrato in Endpoint di recupero dei dettagli del messaggio, quando IO ti richiederà i dettagli del messaggio dovrai indicare i metadati degli allegati (nome e relativa URL); quando il destinatario selezionerà un allegato in app, IO recupererà i byte presso i tuoi sistemi, tramite l'apposita API descritta in Endpoint di recupero dei byte del singolo allegato.

Se il messaggio veicola informazioni sensibili, devi impostare il flag require_secure_channels=true

Fase di fruizione del messaggio

Cosa succede quando il destinatario apre un messaggio a contenuto remoto?

In questa fase, IO verifica le informazioni necessarie per il recupero del messaggio presso gli endpoint da te esposti.

Ogni chiamata da IO verso i tuoi sistemi è identificata dall'id * di correlazione remota che avevi indicato in fase di #creazione-del-messaggio-remotizzato e, come header, il fiscal_code* del destinatario.

In particolare, se in fase di #creazione-del-messaggio-remotizzato avevi indicato has_precondition con valore ONCE o ALWAYS, non appena il destinatario seleziona il messaggio dall'elenco messaggi in app per la prima volta (=ONCE) o tutte le volte (=ALWAYS) IO recupererà l'endpoint da richiamare dalle informazioni di configurazione, e invocherà i tuoi sistemi per ottenere in risposta il titolo e il testo del messaggio da mostrare nel pannello a comparsa delle #precondizioni-allapertura.

A fronte della chiamata API all'Endpoint di recupero delle precondizioni all'apertura del messaggio dovrai rispondere come nell'esempio:

{
    "title": "Questo è il titolo delle precondizioni",
    "markdown": "Questo è il testo delle precondizioni in formato **markdown**"
}

Se il destinatario seleziona "Continua", IO procederà con la visualizzazione del messaggio in app; in caso contrario, l'utente verrà riportato all'elenco dei messaggi.

Se in fase di #creazione-del-messaggio-remotizzato avevi indicato has_remote_content=true, titolo e corpo del messaggio saranno recuperati al momento dell'apertura tramite una chiamata che IO farà all'API da te esposta (per i dettagli fai riferimento a Endpoint di recupero dei dettagli del messaggio).

Come nel modello tradizionale, anche a un messaggio con contenuto remoto puoi aggiungere una data di scadenza (due_date) e i dati riferiti a una posizione debitoria (payment_data); tali informazioni sono già remotizzati grazie all'integrazione con il nodo pagoPA.

PreviousInviare un messaggio tradizionale NextAggiungere allegati