Core
API v1.x
1

You are currently looking at the documentation of a previous version of Kuzzle. We strongly recommend that you use the latest version. You can also use the version selector in the top menu.

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 #

Copied to clipboard!
{
  "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 #

Copied to clipboard!
{
  "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 #

Copied to clipboard!
{
  "message": "Authentication Token Expired",
  "type": "TokenExpired"
}