WebSocket

Recommended hook to receive order notifications.

📘

No returnCode in notifications

Unlike the HTTP responses, there is no returnCode apart of the notification responses the WebSocket server sends out EXCEPT for error responses. Once authenticated and fully connected, the only thing that should be checked is the notification "type".

If you aren't familiar with WebSockets, refer to Mozilla MDN for browser compatibility and information. We recommend WebSocket due to its bi-directional communication which allows a client to know if the connection is broken or requires reconnection.

See Quickstart for example on how to connect.

GET /api/v2/websocket

Authorization

Unlike the HTTP notification, registration occurs once you are able to authenticate upon handshake or when the connection has been made. Due to limitations in some libraries and notably the JavaScript API to connect to the WebSocket server, it may not be possible to pass Authorization header during the handshake phase.

As an alternative, token can be passed after connecting to the WebSocket server, but there will be a time window of 20 seconds before the gateway disconnects the client. If no Authorization header is passed beforehand, token MUST be sent in a JSON payload, similar to the following:

JSON

{"accesstoken": "2f1f4339c7b77fa3474bf8ba8852349273e928bb8ad9d186"}

On Success

If authorized, the current list of active orders in JSON will be sent, nearly identical as calling GET /api/v2/activeorders, so that a client can populate with the current state of active orders without having to make another request. The only addition is a "type" property with value "ACTIVE_ORDERS" to provide application a way of identifying response.

JSON

{
  "count": 2,
  "type": "ACTIVE_ORDERS",
  "items": [
    {
      "name": "102",
      "uuid": "f8853c42-3c10-4636-81e3-a3aeb65d9219",
      "orderType": "ON_PREMISE",
      "locationName": "",
      "state": "started",
      "created": "2016-09-22T19:08:52",
      "stateChanged": "2016-09-22T19:08:52",
      "paged": false,
      "elapsedTime": 0
    },
    {
      "name": "6",
      "uuid": "98a3c77c-9aa0-4eea-a17a-93b2f905a6f1",
      "orderType": "ON_PREMISE",
      "locationName": "",
      "state": "started",
      "created": "2016-09-22T19:08:56",
      "stateChanged": "2016-09-22T19:08:56",
      "paged": false,
      "elapsedTime": 0
    }
  ]
}

Afterward, the WebSocket server will ignore any payload sent by the client and will push order changes in JSON payload if any changes occur to active orders. There are 3 types of notifications to look out for:

ORDER_CREATED

When an order is started or manually created, a payload with type: ORDER_CREATED will be sent. In the case where an order has skipped the "started" state and moves directly to "located" state upon detecting a table, notification will be of "ORDER_CREATED" type.

JSON

{
  "stateChanged": "2016-12-09T09:00:23",
 	"seq": 84,
  "paged": false,
  "name": "23",
  "elapsedTime": 0,
	"uuid": "ac3efe43-c9ac-4a4d-8ea5-38bd816ec52f",
  "created": "2016-12-09T09:00:23",
  "orderType": "ON_PREMISE",
  "locationName": "8",
  "state": "located",
  "type": "ORDER_CREATED"
}

ORDER_MODIFIED

When an order is located or cleared, a payload with type: ORDER_MODIFIED will be sent. This can occur if a user moves to a table.

JSON

{
   "elapsedTime": 9, 
   "uuid": "147e7ccd-c17f-45b4-b5d4-bf14e9c0e244", 
   "seq": 196,
   "created": "2015-05-05T13:40:09", 
   "orderType": "ON_PREMISE", 
   "locationName": "22", 
   "state": "located", 
   "stateStarted": "2015-05-05T13:40:18", 
   "type": "ORDER_MODIFIED", 
   "name": "66"
}

ORDER_PAGED

When an order is paged, a payload with type: "ORDER_PAGED" will be sent.

JSON

{
  "stateChanged": "2016-12-09T09:16:34",
  "seq": 89,
  "paged": true,
  "name": "15",
  "elapsedTime": 6,
  "uuid": "0868ee29-caf3-435f-80a2-12b59bd41ce6",
  "created": "2016-12-09T09:16:34",
  "orderType": "ON_PREMISE", 
  "locationName": "23", 
  "state": "located", 
  "type": "ORDER_PAGED"
}

On Error

If there is an error or the time window expires, the error will be sent to the client and the WebSocket connection will close. Errors mirror HTTP error responses.

401 Access Denied (Invalid Token)

Similar to unauthorized HTTP request, the same payload will be sent to client.

JSON

{
  "status": 401,
  "returnCode": -2,
  "message": "Access denied or no access token provided."
}

408 Timeout

Time window to send access token has expired.

JSON

{
  "status": 408,
  "returnCode": -32,
  "message": "Authentication timeout."
}

400 Bad Request

Malformed JSON payload sent by the client.

JSON

{
  "status": 400,
  "returnCode": -31,
  "message": "Invalid JSON payload."
}