View our GitHub

Please visit sails-docs on GitHub to view documentation on your mobile device.

Edit Page


Starts listening for server-sent events from Sails with the specified eventIdentity. Will trigger the provided callback function when a matching event is received.


io.socket.on(eventIdentity, function (msg) {
  // ...
Argument Type Details
1 eventIdentity The unique identity of a server-sent event, e.g. "recipe"
2 callback Will be called when the server emits a message to this socket.
Argument Type Details
1 msg Message sent from the Sails server

Note that the callback will NEVER trigger until one of your back-end controllers, models, services, etc. sends a message to this socket. Typically that is achieved one of the following ways:

Resourceful Pubsub Methods
Low-Level Socket Methods
  • server emits a message to all known sockets (see sails.sockets.blast())
  • server emits a message directly to this socket (io.socket) using its unique id (see sails.sockets.emit())
  • server broadcasts to a room in which this socket (io.socket) has been allowed to join (remember that a socket only stays subscribed as long as it is connected-- i.e. as long as the browser tab is open)


Listen for new orders and updates to existing orders:

io.socket.on('order', function onServerSentEvent (msg) {
  // msg => {...whatever the server published/emitted...}
Another example, this time using Angular:

Note that this Angular example assumes the backend calls publishCreate() at some point.

angular.module('cafeteria').controller('CheckoutCtrl', function ($scope) {

  $scope.orders = $scope.orders || [];

  if (!io.socket.alreadyListeningToOrders) {
    io.socket.alreadyListeningToOrders = true;
    io.socket.on('order', function onServerSentEvent (msg) {

      // Let's see what the server has to say...
      switch(msg.verb) {

        case 'created':
          $scope.orders.push(; // (add the new order to the DOM)
          $scope.$apply();              // (re-render)

        default: return; // ignore any unrecognized messages

Handle Socket 'Connect' and 'Disconnect' events

If connection to server was interrupted - server was restarted or some network issue - it is possible to handle these events and subscribe to sockets again.

io.socket.on('connect', function(){

  io.socket.on('disconnect', function(){
      console.log('Lost connection to server');


  • When listening for resourceful pubsub calls, the eventIdentity is the same as the identity of the calling model (e.g. if you have a model "UserComment", the identity is "usercomment".)
  • For context-- these types of server-sent events are sometimes referred to as "comet") messages.

Is something missing?

If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the sails-docs repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.


We wrote a book!

Get early access to the book
with promotion code: mcneildoc

Get the Book