Realtime Notifications #

With Kuzzle, you don't subscribe to a room or a topic but, instead, you subscribe to documents. This means, that when you want to subscribe you must provide a set of filter definitions, using Koncorde, that tell Kuzzle what documents should trigger a notification. Then, any time a document matches the defined filters, Kuzzle will send a notification to the subscriber.

You can also provide an empty set of filters, which will tell Kuzzle that you want to listen to any change occurring on a collection, emulating the behavior of a traditional topic.

To subscribe, you must provide a callback that will be called each time a new notification is received.

Once you have subscribed, depending on the subscription configuration you provided, you may receive a notification when:

• a pub/sub message matches your criteria (real-time)
• a matching document is about to be created or deleted in real-time (deactivated by default)
  Deprecated since 1.5.0
• a matching document is created, updated or deleted (once the change is effective in the database)
• a user enters or leaves the room (deactivated by default)

You may subscribe multiple times to the same room, with identical or different subscription parameters, and with different callbacks. This allows you to dispatch notifications to dedicated processes of your application, instead of maintaining a single all-purpose notification consumer (but you can do that too I you want).

Document Notification #

Example #

{
  "status": 200,
  "requestId": "bc41ced6-38fc-42b9-8fd5-22ae0774aac2",
  "controller": "name of the controller that generated the notification",
  "action": "name of the action that generated the notification",
  "collection": "collection name",
  "index": "index name",
  "volatile": {},
  "state": "done",
  "scope": "in",
  "type": "document",
  "document": {
    "content": {
      "content": "document content example"
    },
    "id": "<document identifier (when applicable)>"
  }
}

User notification #

Example #

{
  "status": 200,
  "roomId": "ID of the room concerned by this notification",
  "requestId": "5897cd2f-a8a2-40b2-aa43-b31898172008",
  "controller": "subscribe",
  "user": "in",
  "protocol": "protocol used by the notifying user",
  "timestamp": 1453193069592,
  "volatile": {
    "optional": "user information"
  },
  "type": "user",
  "result": {
    "count": 42
  }
}