Concept: Message Acknowledgement

Back to overview

Message acknowledgement requests and how to confirm them.

Description

Each message defines whether it requires an acknowledgement, when it should be confirmed, the possible error codes and which message type is allowed to send a confirmation.

Unless otherwise specified, a message SHOULD be acknowledged after all associated data has been delivered to the server or immediately in case of an error. In case the app disconnects from the client (e.g. due to the app being suspended), the client SHOULD wake up the app recurrently as long as there are pending acknowledgements. This ensures that all pending messages towards the server are being delivered. All changes to this protocol SHOULD follow this principle. A message MAY deviate from this rule of thumb if there are continuous status updates referencing the message. In such a case, it MUST explicitly state that waking up the app is required until a specific event occurs.

An acknowledgement is being requested by setting the id field of the message. The id MUST be of type String which SHALL contain at least a single character. In addition, id MUST be unique enough to not clash with other pending acknowledgement requests.

In case the message that requested the acknowledgement has been processed completely, a confirmation MUST be sent. The confirmation is part of a message in which the ack field MUST be set to the below displayed Map. Each message requesting an acknowledgement defines under which circumstances the confirmation is a success or an error. In case of a success, the acknowledgement SHOULD only be confirmed with the defined message types. On error, the confirmation SHOULD be sent in form of an update/confirm message.

Field Description Type Optional Nullable
id

The id of the corresponding acknowledgement request

String False False
success

Whether the confirmation indicates a success

Boolean False False
error

The error code which MUST be presented in case success=false and MUST be one of the error codes defined by the message that requested the acknowledgement

String True False