Real-time Notifications #

Clients can subscribe to documents, messages and events, in order to receive a notification whenever a change occurs matching the subscription scope.

Documents changes & messages #

The following notifications are sent by Kuzzle whenever one of the following event matches the subscription filters:

A real-time message is sent
A new document has been created
A document has been updated or replaced
Deprecated since 1.5.0
A document is about to be created (creation not guaranteed)

Real-time notifications are also sent when documents, previously in the subscription scope, are leaving it because of the following events:

document is deleted
document is updated/replaced and its new content do not match the subscription filters anymore
Deprecated since 1.5.0
document is about to be deleted (deletion not guaranteed)

Format #

A document notification contains the following fields:

Property	Type	Description
`action`	string	API controller's action
`collection`	string	Data collection
`controller`	string	API controller
`index`	string	Data index
`protocol`	string	Network protocol used to modify the document
`result`	object	Notification content
`room`	string	Subscription channel identifier. Can be used to link a notification to its corresponding subscription
`scope`	string	`in`: document enters (or stays) in the scope `out`: document leaves the scope
`state`	string	Deprecated since 1.5.0 `done`: the change has been applied `pending`: the change is about to happen
`timestamp`	number	Timestamp of the event, in Epoch-millis format
`type`	string	`document`: the notification type
`volatile`	object	Request volatile data

The result object is the notification content, and it has the following structure:

Property	Type	Description
`_id`	string	Document unique ID `null` if the notification is from a real-time message
`_meta`	object	Deprecated since 1.3.0 Document metadata information (creation time, last update time, and so on). Can be null.
`_source`	object	The message or full document content. Not present if the event is about a document deletion

Example #

{
  "index": "foo",
  "collection": "bar",
  "controller": "document",
  "action": "create",
  "protocol": "http",
  "timestamp": 1497513122738,
  "volatile": null,
  "scope": "in",
  "state": "done",
  "result":{
    "_source":{
      "some": "document content",
      "_kuzzle_info": {
        "author": "<author kuid>",
        "createdAt": 1497866996975,
        "active": true
      }
    },
    "_id": "<document identifier>"
  },
  "room":"893e183fc7acceb5-7a90af8c8bdaac1b"
}

User Notification #

User notifications are triggered by the following events:

A user subscribes to the same room
A user leaves that room

These notifications are sent only if the users argument is set to any other value than the default none one (see subscription request).

Format #

Property	Type	Description
`action`	string	API controller's action
`collection`	string	Data collection
`controller`	string	API controller
`index`	string	Data index
`protocol`	string	Network protocol used by the entering/leaving user
`result`	object	Notification content
`room`	string	Subscription channel identifier. Can be used to link a notification to its corresponding subscription
`timestamp`	number	Timestamp of the event, in Epoch-millis format
`type`	string	`user`: the notification type
`user`	string	`in`: a new user has subscribed to the same filters `out`: a user cancelled a shared subscription
`volatile`	object	Request volatile data

The result object is the notification content, and it has the following structure:

Property	Type	Description
`count`	number	Updated users count sharing that same subscription

Example #

{
  "index": "<index name>",
  "collection": "<collection name>",
  "controller": "realtime",
  "action": "subscribe",
  "protocol": "websocket",
  "timestamp": 1497517009931,
  "user": "in",
  "result": {
    "count": 42
  },
  "volatile": {
    "fullname": "John Snow",
    "favourite season": "winter",
    "goal in life": "knowing something"
  }
}

Server Notification #

Server notifications are triggered by global events, and they are sent to all of a client's subscriptions at the same time.

Currently, the only event generating a server notification is when an authentication token has expired, closing the subscription.

Other events may be added in the future.

Format #

Property	Type	Value
`message`	string	Server message explaining why this notification has been triggered
`type`	string	`TokenExpired`: notification type

Example #

{
  "message": "Authentication Token Expired",
  "type": "TokenExpired"
}

Edit this page on Github