===============================
Disposition Notification Format
===============================

.. contents::
   :local:
   :depth: 3

Overview
~~~~~~~~

Disposition notifications can be requested by the sending party. As per :ref:`fetch_messages_webservice` response documentation, the intent of getting the disposition notification is expressed by the presence of ``disposition_notification`` node for each message.  E.g. ``<disposition_notification>xkXRBMCL.twvNcfC9:positive-delivery, display</disposition_notification>``. The value is split by ``:`` in two parts. First part is the ``message-id`` to be used when building the notification, the second part is the comma delimited list of the requested notifications. If there's ``positive-delivery`` in the list, the ``delivery-notification`` needs to be generated. If there's ``display`` in the list, the ``display-notification`` needs to be generated.


The content-type of the disposition notification is ``application/x-acro-disposition-notification``.

Format
~~~~~~~

.. code-block:: json

	{
		"message-id" : "xkXRBMCL.twvNcfC9",
		"delivery-notification" :
		{
			"datetime" : "2018-26-07T01:02:03Z",
			"status" : "delivered"
		},
		"display-notification" :
		{
			"datetime" : "2018-26-07T01:02:03Z",
			"status" : "displayed"
		}
	}

alternatively, multiple disposition notifications can be grouped in a json array

.. code-block:: json

	[
		{
			"message-id" : "message.1",
			"..." : "..."
		},
		{
			"message-id" : "message.2",
			"..." : "..."
		},
	]



message-id
	Mandatory. It identifies the message being confirmed and comes from the fetch messages response.

delivery-notification
	This node is present when the user agent is notifying the other party that the message was delivered to the device.

	datetime
	 	It is the date and time :rfc:`3339` of the moment when the device got the message.

	status
		Only possible value is ``delivered``


display-notification
	This node is present when the user agent is notifying the other party that the message was displayed to the useruser.

	datetime
	 	It is the date and time :rfc:`3339` of the moment when user displayed the message.

	status
		Only possible value is ``displayed``


Implementation
~~~~~~~~~~~~~~

If the server sends the current time in the fetch response, the server/local clock difference should be computed and ``datetime`` fields in the disposition notifications should be adjusted by the computed clock difference.

.. note::

	The display notification needs to be sent and the correct datetime needs to be set only after the user displays the message. The clock difference at that time may be completely different but we still use the clock difference detected during the fetch time - can't think of any other solution.

.. important::

	If the delivery of the disposition notification fails because of the transmission problems or the server responds wih 5xx HTTP code, the disposition notification delivery should be retried later.