---
title: Use of WebSockets - App partners
description: Connecting to the Doshii WebSocket Service is a vital point in the API process flow. It allows you to receive events from the POS in real-time rather than continuously "long" polling the server to fin
---

[Skip to content](https://support.doshii.com/developer-support/hc/en-us/articles/360000649633-use-of-websockets-app-partners#main-content)

English

Show submenu for translations

Doshii Connect Pty Ltd

Open main navigation

Close main navigation

- English
  
  Show submenu for translations
- Go to Doshii Connect Pty Ltd

 Go to Doshii Connect Pty Ltd

 Help for Partners

- There are no suggestions because the search field is empty.

1. [Help for Partners](https://support.doshii.com/developer-support?hsLang=en)
2. [WebSocket - App partners](https://support.doshii.com/developer-support/websocket-app-partners?hsLang=en)

# Use of WebSockets - App partners

Connecting to the Doshii WebSocket Service is a vital point in the API process flow. It allows you to receive events from the POS in real-time rather than continuously "long" polling the server to find updates.

The following examples are using NodeJS.

[Environments](https://support.doshii.com/developer-support/hc/en-us/articles/360000649633-use-of-websockets-app-partners#environments)

[Connection](https://support.doshii.com/developer-support/hc/en-us/articles/360000649633-use-of-websockets-app-partners#manual-connection)

[Best practices](https://support.doshii.com/developer-support/hc/en-us/articles/360000649633-use-of-websockets-app-partners#h_01GKFS1WV1DKSAB85KMQFX133P)

 

 Environments

There are currently two environments available in establishing a **[connection](https://support.doshii.com/developer-support/partner-connection?hsLang=en)** to the Doshii WebSocket. If you're pre-launch (ie. don't have live credentials), that will be the `sandbox` environment. If you're a live integrator, it will be the aptly named `live` environment.

```
// Sandbox
wss://socket.sandbox.doshii.co/app/socket?auth=<>

// Live
wss://live-socket.doshii.co/app/socket?auth=<> 
```

 

With `` representing the base64 encoding of `YOUR_DOSHII_CLIENT_ID`

Already using a different URL than above? Older naming patterns for the URL will continue to work.

 

 Connection

Here's a JavaScript guide for you on how to establish the connection with Doshii. Those writing other languages will need to adapt the following to suit, guides for your language are coming soon. Further details around the connection can be found **[here](https://support.doshii.com/developer-support/partner-connection?hsLang=en)**.

Let's start by installing a couple of libraries you'll need to make the connection.

- [WebSockets "ws"](https://github.com/websockets/ws) library for fast and easy WebSocket connection
- [btoa](https://www.npmjs.com/package/btoa) library. It turns binary data to base64-encoded ascii.

```

yarn add btoa ws
# Or for you NPMers
npm i -S btoa ws
```

 

Now that's all done, let's establish a connection.

```

var WebSocket = require('ws');
var btoa = require('btoa');

var authToken = btoa(YOUR_DOSHII_CLIENT_ID);

// Establish a connection to the Doshii Sandbox WebSocket
var ws = new WebSocket('wss://socket.sandbox.doshii.co/app/socket?auth=' + authToken);
```

 

After you've connected to the Doshii WebSocket, you'll need to send **[heartbeats](https://support.doshii.com/developer-support/hc/en-us/articles/360007382954-heartbeats?hsLang=en)** across every 30 seconds so that we know you're still listening.

```
ws.on('open', function(event) {
  function heartbeat() {
    const timestamp = Date.now();
    const appVersion = '1.2.3';
    const payload = JSON.stringify({
        doshii: {
            ping: timestamp,
            version: appVersion
        }
    });
    ws.send(payload);
  }

  heartbeat(); // Send one immediately to complete the handshake
  setInterval(heartbeat, 30000); // Then 30 every seconds or so thereafter to keep alive
});
```

 

It's a good idea to have some error handling in there too.

```
ws.on('error', function(err) {
  throw new Error('Doshii WebSocket error: ', err);
});
```

 

Great! Now that you're connected and errors handled, how about we listen for some messages from the server?

```
ws.addEventListener('message', function(event) {
  if (!event) return;
  console.log(event.type);
  console.log(event.data);
}
```

 

The important parts of the event you'll receive are `event.type` and `event.data`. The `event.type` field stores the name of the event that corresponds with the list found in the **[Partner API Reference](https://support.doshii.com/developer-support/all-app-partners-event?hsLang=en)**. For example; `order_created` or `transaction_updated`. Generic messages such as the "pong" response to each of your "ping"s will have the `message` event type. The `event.data` field stores the relevant information of the event.

Here's a sample "pong" message event.

```
{
  type: 'message',
  data: {
        doshii: {
            pong: 1539144663417,
            version: '3.2.123'
        }
    },
  target:
    WebSocket {
      ... (connection information)
    }
}
```

 

A list of the WebSocket events can be found in the [**Partner API Reference**.](https://support.doshii.com/developer-support/all-app-partners-event?hsLang=en)

 

 Best practices

- Use appropriate GET requests with limited parameters (ie: to/from) to retrieve any events potentially missed since last connection.
- Keep the socket channel open for subsequent events whilst processing the first on a background/asynchronous thread.
- Use the full `uri` parameter/attribute of events to reference the entity to which an event pertains (rather than by `id`).

 

- [API concepts](https://support.doshii.com/developer-support/api-concepts?hsLang=en)
- [Members](https://support.doshii.com/developer-support/members?hsLang=en)
- [Model](https://support.doshii.com/developer-support/model?hsLang=en)
- [FAQ - Developers](https://support.doshii.com/developer-support/faq-developers?hsLang=en)
- [Resources](https://support.doshii.com/developer-support/resources?hsLang=en)
- [Orders](https://support.doshii.com/developer-support/orders?hsLang=en)
- [Rewards](https://support.doshii.com/developer-support/rewards?hsLang=en)
- [Check-ins](https://support.doshii.com/developer-support/check-ins?hsLang=en)
- [Getting started - App partners](https://support.doshii.com/developer-support/getting-started-app-partners?hsLang=en)
- [Employees](https://support.doshii.com/developer-support/employees?hsLang=en)
- [Getting started - Doshii Dashboard](https://support.doshii.com/developer-support/getting-started-doshii-dashboard?hsLang=en)
- [Quick start for developers](https://support.doshii.com/developer-support/quick-start-for-developers?hsLang=en)
- [Onboarding](https://support.doshii.com/developer-support/onboarding?hsLang=en)
- [Location](https://support.doshii.com/developer-support/location?hsLang=en)
- [All App Partners Event](https://support.doshii.com/developer-support/all-app-partners-event?hsLang=en)
- [Menus](https://support.doshii.com/developer-support/menus?hsLang=en)
- [Loyalty / Checkins](https://support.doshii.com/developer-support/loyalty-checkins?hsLang=en)
- [WebSocket - App partners](https://support.doshii.com/developer-support/websocket-app-partners?hsLang=en)
- [All POS vendor events](https://support.doshii.com/developer-support/all-pos-vendor-events?hsLang=en)
- [Loyalty / Gift Cards](https://support.doshii.com/developer-support/loyalty-gift-cards?hsLang=en)
- [Devices](https://support.doshii.com/developer-support/devices?hsLang=en)
- [Tables](https://support.doshii.com/developer-support/tables?hsLang=en)
- [Workflows](https://support.doshii.com/developer-support/workflows?hsLang=en)
- [FAQ - Doshii Dashboard](https://support.doshii.com/developer-support/faq-doshii-dashboard?hsLang=en)
- [Bookings](https://support.doshii.com/developer-support/bookings?hsLang=en)
- [Transactions](https://support.doshii.com/developer-support/transactions?hsLang=en)
- [Webhooks](https://support.doshii.com/developer-support/webhooks?hsLang=en#main-content)

    - [App Partners](https://support.doshii.com/developer-support/webhooks?hsLang=en#app-partners)
    - [POS Vendors](https://support.doshii.com/developer-support/webhooks?hsLang=en#pos-vendors)
- [App Partner Guide](https://support.doshii.com/developer-support/app-partner-guide?hsLang=en)
- [Authentication](https://support.doshii.com/developer-support/authentication?hsLang=en)
- [Getting started - POS vendors](https://support.doshii.com/developer-support/getting-started-pos-vendors?hsLang=en)
- [Ordering](https://support.doshii.com/developer-support/ordering?hsLang=en)
- [Reservations](https://support.doshii.com/developer-support/reservations?hsLang=en)
- [Pilot](https://support.doshii.com/developer-support/pilot?hsLang=en)
- [Bulk data](https://support.doshii.com/developer-support/bulk-data?hsLang=en)
- [Playbooks](https://support.doshii.com/developer-support/playbooks?hsLang=en)
- [Rejection codes](https://support.doshii.com/developer-support/rejection-codes?hsLang=en)
- [Getting started](https://support.doshii.com/developer-support/getting-started?hsLang=en)
- [WebSocket - POS partners](https://support.doshii.com/developer-support/websocket-pos-partners?hsLang=en)
- [Events - App partners](https://support.doshii.com/developer-support/events-app-partners?hsLang=en)
- [Service channels](https://support.doshii.com/developer-support/service-channels?hsLang=en)
- [Events](https://support.doshii.com/developer-support/events?hsLang=en)
- [Concepts](https://support.doshii.com/developer-support/concepts?hsLang=en)
- [Apps](https://support.doshii.com/developer-support/apps?hsLang=en)

# Doshii Connect Pty Ltd

Doshii Connect Pty Ltd Help Center

Copyright © 2026, Doshii Connect Pty Ltd