Realtime Messaging with EventSource can act as a real-time messaging hub for your application. You can use the real-time API from web clients and servers, actually any client that can connect to your database using the HTTP EventSource API.

Web clients should use the JavaScript API for you database. Server to server scenarios can use the REST API directly via cURL (or similar).

Read this blog post with a complete code example for a real-time chat.

Access using API keys

Real-time messages are switched off by default for security reasons. There are two ways to enable them:

  1. Set up global access (potentially unsecure)
  2. Control access in the Web API key settings

Enable all realtime messages in global settings

In "Developer Mode", select the "Settings" tab and enter the following configuration:

Settings Tab

    "global": true

Enable specific messages/channels for an API key

In the "Users and Settings" of your database, select the "API" tab and create/edit a Web API key. In the bottom of the dialog, select "Real-time events". Now you can add "channels" and add the REST messages you want to listen to using this API key. The format is <METHOD>:<COLLECTION>, so if you want to listen to "POST" events on the "company" collection, you add POST:company to the list of events. Setting access to real-time events

Access for external users

For instructions on how to use realtime with external users (JWT authenticated), check out the
users and roles documentation.

Realtime messaging using JavaScript EventSource

The server-sent event API is contained in the EventSource interface; to open a connection to the server to begin receiving events from it, create a new EventSource object, specifying the URI to the database realtime event stream. For example:

var evtSource = new EventSource('');

To listen for incoming messages from your database you must listen for typed events, using the addEventListener() method:

evtSource.addEventListener('post', function (e) {
    // do something with, e.g. JSON.parse(
}, false);

evtSource.addEventListener('put', function (e) {
    // do something with
}, false);

// listen for message publishing
evtSource.addEventListener('publish', function (e) {
    // do something with
}, false);

Realtime messaging using the JavaScript API lets you subscribe to Database events in realtime. Create a new database api connection using the auto generated JavaScript API for your database (read the JavaScript API docs here). Read this blog post about a chat application with a complete code example.

var db = new.db("your-CORS-apikey-here | JWT token", {realtime: true});

Note: You must also add realtime access to the web API-key you use. You do this in the "Manage Users and Settings" section of your database.


The API for realtime messaging consists only of two methods:

db.on(event, cb)Listen to database events (POST, PUT, PATCH, DELETE, CONNECT, DISCONNECT, RECONNECT) or custom events (<EVENTNAME>)
db.publish(event, data, cb)Publish custom events (<EVENTNAME>)

Subscribe to database events

db.on(event, callback)

Subscribe to "PUT" or "PATCH" database operations

    db.on("PUT", function(error, eventdata){
      // eventdata format: {event: "put", collection: "the-collection-name", data: "ID"}

Subscribe to "POST" database operations

    db.on("POST", function(error, eventdata){
      // eventdata format: {event: "post", collection: "", data: {_id: ID, ...}}

Subscribe to "DELETE" database operations

    db.on("DELETE", function(error, eventdata){
      // eventdata format: {event: "delete", collection: "the-collection-name", data: ["ID1", "ID2", ...]}

Connection states

The JavaScript API handles all connect and reconnect to the database automatically. However, you can also subscribe to these events with the following code.

Subscribe to "CONNECT" client state

    db.on("CONNECT", function(){
      // flash green stuff to indicate that we're on-line :)

Subscribe to "DISCONNECT" client state

    db.on("DISCONNECT", function(){
      // flash red stuff to indicate that we're off-line :(
      // perhaps you lost the wifi, 4G or the server dropped out?

Subscribe to "RECONNECT" client state

    db.on("RECONNECT", function(){
      // flash green stuff to indicate that we're back in business ;-)

Publish / Subscribe to custom events lets you publish/subscribe custom events that are not related to data changes in your database.

Publish custom events

    db.publish("GOAL", {"match": 223, "value":"3-0"}, function(error, result){
      // if not error result is {"message": "OK"}

Subscribe to custom Messages from applications

    db.on("GOAL", function(error, eventdata){
      // eventdata format: {event: "GOAL", data: {...}}

Realtime messaging using HTTP and cURL

All databases has an endpoint for realtime messages. You can connect to the url with any http-compatible libraries (with EventSource support). In this example we'll be using curl from the command line.

To subscribe to event messages use the GET method. To publish event messages use the POST method.

The example output from a realtime session using curl is shown below:

    curl -i -H "Content-Type: application/json" -H "x-apikey: your-api-key-here" -X GET ''
    HTTP/1.1 200 OK

    retry: 2000

    data: {"channel":"init","data":{}}

    event: ping
    data: 2016-07-06T13:22:01.130Z

    id: 9
    event: put
    data: {"event":"put","collection":"customer","data":"577cf185e2039b0900000016"}
    retry: 10000

The example above shows how the client connects to the endpoint with a GET request. The realtime endpoint sends some headers first, most importantly the connection: keep-alive header. Then it sends some initial metadata to indicate that everything is ok. After a while the server sends an event to the client. In this example it's a PUT event with a data payload about the actual event in the database.

In a similar way we can publish custom events to the realtime API using a POST method.

The example below shows a realtime event published with using HTTP.

    curl -i -H "Content-Type: application/json" -H "x-apikey: you-api-code-here" -X POST -d '{"event":"boing","data":{"name":"value"}}' ''
    HTTP/1.1 200 OK


Links to EventSource API client libraries