WebSocketHandler is used for persistent connections and server-side push.

See this chatbot demo. The chatbot has a single connection to the server that is kept open. This reduces latency. It also allows the server to send a message back to the client when required.

Here is a sample configuration:

        pattern: /pingbot
        handler: WebSocketHandler
            open:                               # When websocket is opened
                function: pingbot.open          #   call open(handler) in pingbot.py
            on_message:                         # When client sends a message
                function: pingbot.on_message    #   call on_message(handler, msg) in pingbot.py
            on_close:                           # When websocket is closed
                function: pingbot.on_close      #   call on_close(handler) in pingbot.py
            origins:                            # Optional: Allow only from these domains.
                - gramener.com                  # If unspecified, all domains are allowed.
                - localhost
            # You can also add the auth: configuration like other handlers. For example:
            # auth: true

This passes on the open, on_message and on_close events to pingbot.py:

def open(handler):
    print('Chatbot opened for', handler.session['id'])

def on_message(handler, message):
    print('Got message', message, 'for', handler.session['id'])
    handler.write_message('Got message: ' + message)

def on_close(handler):
    print('Chatbot closed for', handler.session['id'])

Now we can use JavaScript to open and interact with the websocket.

// Open the websocket
var url = location.href.replace(/^http/, 'ws') + 'pingbot'
var ws = new WebSocket(url)

// When we receive any message, log it to the console
ws.onmessage = console.log

// Send a message to the server a second later.
setTimeout(function() {
  ws.send('Hello world')
}, 1000)

// You may use ws.close() to close the socket. Sockets automatically close
// when the user closes the page, so this is not often used.
// ws.close()

Now open this browser’s JavaScript console. You should see the message returned by the server.

To learn more about websockets:

Websockets via nginx

To serve WebSockets from behind an nginx reverse proxy, use the following config:

http {
  # Add this configuration inside the http section
  # ----------------------------------------------
  map $http_upgrade $connection_upgrade {
      default upgrade;
      ''      close;

  server {
    location / {
      proxy_pass ...;

      # Add this configuration inside the http > server > location section
      # ------------------------------------------------------------------
      proxy_http_version 1.1;
      proxy_set_header Upgrade    $http_upgrade;
      proxy_set_header Connection $connection_upgrade;
      proxy_set_header Host       $host;
      proxy_set_header X-Scheme   $scheme;