Table of contents
OpenAPI recovery endpoint of remote content
In the case of sending a message traditionally on IO, the institution calls the exposed API for the creation of the message and IO proceeds with its complete management in app:
The following diagram shows the sequence of events that involve your system and the IO system for exchanging information with the recipient of a message with remote content:
Detailed diagram
The sequence of events that make up the life cycle of a remote content message are shown below in more detail:
{% img src="../.gitbook/assets/[Sequence] Messaggi con contenuto remoto.png" alt=` data-size="original" / %}
The following chapters show the detailed sequence of each phase.
Retrieval endpoint of preconditions when opening the message
If during the send-a-message-a-contenuto-remoto.md you included the field Has_precondition (or if you had indicated it in the Remote configuration) phase, at the time when the message is opened by the recipient, IO will retrieve the preconditions through a GET call to your systems, containing the following parameters in input:
- The remote correlation id you indicated in the Third_party_data block when sending the message;
- the fiscal code of the recipient (as the header).
Your systems will need to verify that the fiscal code sent as input exactly matches the intended recipient, and if it does, the contents of the preconditions will be transmitted to IO.
IO will use the base_url, which you communicated when setting the remote configuration information, and the correlation identifier, which you specified in the Third_party_data block, when sending the message, when sending the message, to create a GET call in the form of {base_url}/messages/{id}/precondition:
get
Retrieval endpoint of message details
If during the send-a-message-a-contenuto-remoto.md you included the flag Has_remote_content or, being a Premium institution, the flag Has_attachments, IO must retrieve the content of the messages from your systems at the moment it is displayed in app, and will use the API described here; it will do it with a GET call, with which it will return to you:
- The remote correlation id you indicated in the Third_party_data block when sending the message;
- the fiscal code of the recipient (as the header).
Your system can then retrieve the content of the message, while checking that the received request is actually related to that recipient.
IO will use the base_url, which you communicated to the IO team when setting the remote configuration information, and the correlation identifier, which you specified in the Third_party_data block, when sending the message, to create a GET call in the form of {base_url}/messages/{id}:
\
Be careful: in this case the univocal identifier is the **remote correlation** `id` you indicated in [#third_party_data](message-api/submit-a-message-passing-the-user-fiscal-code-in-the-request-body.md#third_party_data "mention") when sending the message.
{% openapi src="https://raw.githubusercontent.com/pagopa/io-backend/master/openapi/consumed/api_remote_content.yaml" path="/messages/{id}/{attachment_url}" method="get" %} https://raw.githubusercontent.com/pagopa/io-backend/master/openapi/consumed/api_remote_content.yaml \
{% /openapi %}
{% hint style="info" %} The API must return the stream of bytes of the attached file in binary application/octet-stream format. \
{% /hint %}
API Key
IO guarantees that the fiscal code in the request corresponds to fiscal code of the user who is trying to retrieve the message data. The fiscal code is sent through the fiscal\_code header.
{% hint style="warning" %} The institution is responsible for correctly identifying the user's fiscal code. \
{% /hint %}
Note about headers
All the APIs described here include a set of optional header called "x-pagopa-lollipop-..." and two "signature" headers of, which do not have to be valued, but whose reception we ask you not to exclude.
Useful resources
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