Table of contents
Send a message with remote content
What are remote content messages?
Remote content messages address the need to convey through IO communications containing citizens' personal and/or sensitive data, ensuring their management complies with privacy regulations. In fact, by choosing this sending method, the information is not stored on IO, but retrieved from your systems every time the user accesses the message in the app.
For a message, the remotable contents are:
- title;
- body;
- opening preconditions (optional, e.g., disclaimers);
- attachments (Premium).
What changes?
📐 Architecture
Unlike traditional sending, which involves transmitting the message contents to IO systems at the time of its creation, remote messages ensure that these contents reside exclusively on your systems and IO will retrieve them every time the recipient user wants to view them in the app.
.png)
This way, IO acts as a real-time communication channel between you and your user and only holds the information necessary to allow the retrieval of the message and verify its status.
🕵️♂️ Managing sensitive information
As specified, remote messages are designed to ensure a privacy-compliant delivery of personal/sensitive information referring to the recipient, where necessary for the provision of the service.
As a further measure to protect privacy, the Require_secure_channels flag allows you to mark a message as containing sensitive information, with the following effects:
- push notifications on the recipient's devices will show a generic invitation to open the message, without displaying the content of the title;
- messages will not be forwarded via email regardless of the preference set by the recipient user.
✏️ Content updating over time
Unlike traditional messages, remote content messages can be modified even after sending: for example, you can correct a typo, or dynamically update information that is no longer valid or misleading (e.g., following the cancellation of an appointment).
When considering this possibility, it is worth remembering that:
- The recipient user will not receive any notification in case of an update to the content of a previously received message. In fact, the content can only be refreshed, calling it back from your systems, only when and if the user opens the message in the app;
- The responsibility for the information transmitted via IO remains in any case with the sending entity.
Appointment booking use case - Example of updating message contents after sending
- Your entity sends a remote content message to the recipient citizen to confirm the booking of a healthcare appointment:
- The recipient reads the message and decides to cancel the appointment through the channels you made available for booking management;
- Your entity sends the same user a new message to confirm the cancellation;
- To ensure informational consistency, your entity updates the contents of the first message by replacing and/or removing the appointment confirmation information and obsolete references.
To make the recipient aware that the contents could be updated over time, the following notice has been included at the bottom of the details of all remote content messages, in its short and extended versions:
.png)
.png)
How does sending a remote content message work?
The lifecycle of a remote content message consists of two main stages:
- Sending (creation) by your organization's systems;
- Fruition (viewing) by the recipient.
Both phases require integration between your systems and IO's.
Message sending phase
Creating a remote-content message
At this stage, your systems integrated with IO request the creation—and therefore the sending—of a new message to a specific recipient. For more information about sending a message through IO, see ..
The following table summarises the main components of an IO message that can be served remotely:
| Component | Flag to set | Notes | Can be served remotely? |
|---|---|---|---|
| preconditions | Has_precondition | These are optional information displayed before the message details are opened. | |
| title (subject) | Has_remote_content | This is the title displayed when the message is opened. It differs from the title shown in the message list, which cannot be served remotely. | |
| body (markdown) | Has_remote_content | This is the text content of the message. | |
| payment notice details | These are already served remotely through integration with the pagoPA node. | ||
| attachments (PDF) | Has_attachments | This content can only be managed remotely. You can include it if you have signed the Premium Agreement. PDF is the accepted format. |
Important information about preconditions displayed before opening a message
As the sending organisation, you can require the opening of a message to be preceded by content intended to inform the recipient about specific aspects or circumstances relating to the message itself.
Preconditions are displayed on an intermediate screen between the message list and the details of the selected message. The user can access the message details only by selecting the "Continue" button.
.png)
Displaying preconditions interrupts the message-reading flow. You should therefore use them only when they provide real value to your communication or are required by applicable legislation, so as not to degrade the user experience.
When to use them:
When it is necessary to draw the citizen's attention to essential information, and whenever required by applicable legislation—for example, in legally binding communications where opening the message has legal effects for the citizen.
When it is necessary to draw the citizen's attention to essential information, and whenever required by applicable legislation—for example, in legally binding communications where opening the message has legal effects for the citizen.
When not to use them:
To provide notices that are not strictly related to the message content, or to add detailed information that can be included within the message or provided at another stage of the user experience.
To provide notices that are not strictly related to the message content, or to add detailed information that can be included within the message or provided at another stage of the user experience.
Important information about the message title (subject) in relation to the "has_remote_content" flag
The message title is used by the IO app in three situations:
- as the title displayed in the list of received messages;
- as the heading of the message details after the message is opened;
- in the text of push notifications associated with the message, where enabled by the user and provided that you have not marked the message or service as containing sensitive information.
Depending on the value of the Has_remote_content flag specified in Third_party_data—see later in this chapter—the message title behaves differently:
- if Has_remote_content=true, the Subject field specified when creating the message is used by IO in the list of received messages, as the push-notification text and as the subject of any message-forwarding email. However, it is not used in the message-details view in the app, where the title is retrieved at a later stage (see What happens when the recipient opens a remote content message).
This means that the recipient may see different text inside and outside the message-details view. We recommend that you do not make substantial changes to the title, so that the two versions remain consistent. Please also remember that, under the IO Guidelines, sensitive information cannot be included in the message title. - if Has_remote_content=false, or if you do not include the flag, the Subject field follows the standard behaviour of a traditional, non-remote message: the same text is used in the message details and in all the other contexts listed above.
Important information about the message body (markdown)
When creating a remote-content message (Has_remote_content=true), you must still comply with the IO API interface by providing a non-remote fallback text in markdown. This text is used to compose the message-forwarding email that IO users can choose to receive when a message is delivered to them in the app.
Markdown limits for forwarding: minimum 80 and maximum 134 characters. Any additional text is truncated and replaced with an ellipsis.
Note about forwarding messages by email: If enabled by the end user, a message sent through IO can be forwarded to their email address. The email contains the beginning of the message body—the first 134 characters—together with an invitation to open the app and access the complete content through a redirect CTA. The following is an example of a forwarding email:
For remote-content messages, you must include the following additional information in the Third_party_data block:
| Field | Field description |
|---|---|
| Id | This is the remote correlation identifier, which uniquely identifies a specific message addressed to a specific recipient. The identifier is defined by you and consists of a string that allows the APIs to retrieve the remote content for that specific message. |
| Configuration_id | Enter the identifier you received during Remote configuration. IO uses this value to determine the information required to call the REST endpoints exposed by your organisation, which provide the remote data for the message. |
| submit-a-message-passing-the-user-fiscal_code-in-the-request-body.md | Set this field only if, when the message is opened in the app, you want the recipient to see text—with a related title—containing contextual information that you provide at that time. For more information, see openapi-endpoint-di-recupero-dei-contenuti-remotizzati.md. After reading the text, the recipient can choose whether to continue opening the message or return to the list of received messages. The possible values for this field are:
|
| submit-a-message-passing-the-user-fiscal_code-in-the-request-body.md | Set this field to true if you want the message title (subject) and body to be served remotely. When IO requests them through the dedicated API that you have exposed, you must respond with a text string for the title and markdown for the body, just as you would have specified them when creating a traditional message. The default value for this field is false. For more information and to understand the role of the title in a remote-content message, see openapi-endpoint-di-recupero-dei-contenuti-remotizzati.md. |
| submit-a-message-passing-the-user-fiscal_code-in-the-request-body.md | Set this field to true if you want to attach one or more PDF documents to the message. As described in openapi-endpoint-di-recupero-dei-contenuti-remotizzati.md, when IO requests the message details, you must provide the attachment metadata—name and corresponding URL. When the recipient selects an attachment in the app, IO retrieves the bytes from your systems through the dedicated API described in openapi-endpoint-di-recupero-dei-contenuti-remotizzati.md. Remember that you can set this flag only if the organisation has signed the IO Premium Agreement. |
Message access phase
What happens when the recipient opens a remote-content message?
At this stage, IO uses the flags specified when the message was created to determine how to compose it in the app. Where necessary, IO retrieves the remote data and combines it with the information it already holds before presenting the final result to the recipient.
In particular, if you set submit-a-message-passing-the-user-fiscal_code-in-the-request-body.md to ONCE or ALWAYS during inviare-un-messaggio-a-contenuto-remoto.md, when the recipient selects the message from the in-app message list—only if they have never opened it before for ONCE, or every time for ALWAYS—IO retrieves the endpoint to call from the configuration information and calls your systems to obtain the precondition title and text to display in the inviare-un-messaggio-a-contenuto-remoto.md pop-up panel.
In response to a call to the openapi-endpoint-di-recupero-dei-contenuti-remotizzati.md API endpoint, return a response such as the following:
1{
2 "title": "This is the precondition title",
3 "markdown": "This is the precondition text in **markdown** format"
4}
5The precondition panel contains two buttons: "Cancel" and "Continue".
If the recipient selects "Continue", IO displays the message in the app. Otherwise, the user is returned to the message list.
If you set submit-a-message-passing-the-user-fiscal_code-in-the-request-body.md=true during inviare-un-messaggio-a-contenuto-remoto.md, the message title and body are retrieved when the message is opened, through a call made by IO to the API you exposed. For details, see openapi-endpoint-di-recupero-dei-contenuti-remotizzati.md.
Haven't completed onboarding yet and need help?
Write an email describing your problem or question to the address areariservata@assistenza.pagopa.it.
Tell us what you think
To report problems or give feedback, leave a comment in the GitHub space of the IO app