Dialog events

Description

When a client calls this endpoint, the server does not return immediately, but keeps the connection open until it is explicitly disconnected or a network error occurs. This method is called Server Sent Events (SSE), and is a way for the server to notify connected clients about server side events. Event are sent from the server to the client via the open connection. Whan a new client connects, the server immediately sends a clientRegistered event to the client. This event contains information about the client's supported report area(s) and whether there are any unread dialog messages available. If there are any unread dialogs, the client should download them, perform processing and mark them as read. After that, the client should wait for new events from the server.

Endpoint

[GET] /api/v2/dialog/events

Scope

Required scope:
nhn:melde/dialog/melding

Response

This endpoint does not return a response the normal way. Insted it keeps the connection open and use it as an event transport route to the client. The events sent from the server are wrapped in a standard SSE 'envelope'. The event payload looks like this:

{
    "ReportArea": nn,                 // Report area id
    "EventType": "",                  // One of clientRegistered, newDialog, newMessage, dialogDeleted, readMessages
    "DialogRef": "",                  // Dialog reference 'Dxxxx'
    "ReportRef": "",                  // Report reference 'Vxxxx'
    "HasUnreadMessages": true|false   // true, false or null if not relevant
}

The server may send the following events:

• clientRegistered
  This event is sent to the client right after the connection has been established and the client connection is registered by the server. When receiving this event, the client should request the Dialog unread messages endpoint to ensure that all unread messages are downloaded from Melde.
• newDialog
  This event is sent to the client when a new dialog is created. The case worker side will currently never receive this event type, since it is only the case worker side who is allowed to create new dialogs.
• newMessage
  This event is sent to the client when new message(s) are ready to be downloaded. The client should then request the Fetch new messages endpoint to download the message(s).
• dialogDeleted
  This event is sent to the client when a dialog is deleted. Melde is allowed to store messages for 4 months after the newest dialog message timestamp in a dialog, due to privacy policy.
• readMessages
  This event is sent to the client when the message recipient has read a message.

Example client

An example client can be found in the Example.Dialog folder in this Github repository (opens in new tab).