Tabella dei contenuti
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 al momento della sua creazione, 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.
.png)
Sequenza delle principali fasi nei due scenari di invio
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.
🕵️♂️ 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.
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.
✏️ 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.
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:
.jpg)
Informativa breve, in calce al messaggio
.jpg)
Informativa estesa, consultabile tramite la CTA "Scopri di più"
Come funziona l’invio di un messaggio a contenuto remoto?
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.
.png)
Le due fasi principali del ciclo di vita di un messaggio a contenuto remoto
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 ..
La tabella che segue riepiloga le principali componenti remotizzabili di un messaggio IO:
| Componente | Flag da impostare | Note | Remotizzabile? |
|---|---|---|---|
| precondizioni | Has_precondition | Si tratta di informazioni opzionali, che vengono mostrate prima dell'apertura del dettaglio del messaggio. | |
| titolo (subject) | Has_remote_content | Si tratta del titolo visibile all'apertura del messaggio, che differisce da quello visibile nella lista messaggi (non remotizzabile). | |
| corpo (markdown) | Has_remote_content | 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) | Has_attachments | 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 è 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.
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 in relazione al flag "has_remote_content"
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 nell'elenco dei messaggi ricevuti, come testo della notifica push e come subject dell'eventuale email di inoltro del messaggio, ma non nella vista di dettaglio del messaggio in app: questa è invece recuperata successivamente (vedi Cosa succede quando il destinatario apre un messaggio remotizzato).
Questo significa che il destinatario potrebbe vedere testi differenti nel dettaglio del messaggio e fuori. Consigliamo di non differenziare 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 nel dettaglio del messaggio e in tutti gli altri contesti sopra citati.
Informazioni importanti circa il corpo (markdown) del messaggio
In fase di creazione di un messaggio a contenuto remoto ( Has_remote_content=true) , è 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:
.png)
Per i messaggi a contenuto remoto, è obbligatorio inserire le seguenti informazioni aggiuntive nel blocco Third_party_data:
| 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. |
| Configuration_id | Indica in questo campo l'identificativo che hai ricevuto in fase di Configurazione remota: IO utilizzerà questo dato per determinare il set di informazioni necessarie per richiamare gli endpoint REST esposti dalla tua Organizzazione che serviranno i dati remoti per questo 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 allapertura 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:
|
| 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. Ricorda che puoi impostare questo flag solo se l'ente ha sottoscritto l'Accordo Premium di IO. |
Fase di fruizione del messaggio
Cosa succede quando il destinatario apre un messaggio a contenuto remoto?
In questa fase, IO utilizza i flag che avevi indicato in fase di creazione per determinare come comporre il messaggio in app, e procede quindi all'eventuale recupero dei dati remoti e alla loro integrazione con quelli già in suo possesso per presentare il risultato finale al 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 non avendolo ancora mai letto (=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 delle precondizioni da mostrare nel pannello a comparsa delle Precondizioni allapertura.
A fronte della chiamata API all'Endpoint di recupero delle precondizioni allapertura del messaggio dovrai rispondere come nell'esempio:
1{
2 "title": "Questo è il titolo delle precondizioni",
3 "markdown": "Questo è il testo delle precondizioni in formato **markdown**"
4}
5Il pannello delle precondizioni presenta due pulsanti: "Annulla" e "Continua".
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).
Hai bisogno di aiuto?
Scrivi un’email in cui descrivi il tuo problema o dubbio all’indirizzo onboarding@io.italia.it
Dicci cosa ne pensi
Per segnalare problemi o dare feedback, lascia un commento nello spazio Github dell'app IO