top of page

Getting started with Pulsoid API using JavaScript


Pulsoid is real-time heart rate streaming platform. Pulsoid can obtain heart rate data from Apple Watch, WearOS watches, IOS and Android phones. The goal of Pulsoid API is to hide the complexity of obtaining heart rate and to provide simple, fast, secure and reliable way to transfer this data to 3rd-party developers and applications.


The core of Pulsoid Read API is a WebSocket connection. WebSocket is a computer communications protocol that provides communication channels over a single TCP connection. WebSocket implementation improves delivery time of the heart rate data and makes it almost instantaneous.

Obtaining a user access token is the first step of using Pulsoid as a platform.

How to obtain a user access token?

To simplify JavaScript integration, we developed a dedicated library for handling reliable WebSocket connection to the Pulsoid server. Basic usage of the library can be described in several steps:


1. Install pulsoid/socket npm package

2. Initialize PulsoidSocket object

3. Subscribe to the heart rate. Heart rate message contains two fields

  • measuredAt - a unix timestamp in millis of when heart rate was meassured on user’s device. Note: there are cases when user’s device time can differ from the real one for 30+ seconds.

  • heartRate - heart rate in beats per minute



Complete documentation is available on our github.


WebSocket is a stateful protocol so graceful handling of reconnects is important. It helps ensure that the client can continue to communicate with the server without interruption, even if there are temporary network issues or other problems that cause the connection to be lost. This is especially important for Pulsoid, where real-time communication is critical. Also, opened WebSocket connection doesn’t mean that there is heart rate data.

To address these points, we created two layers of events:

  • Connected/Disconnected/Reconnecting events describe state of WebSocket connection itself. In most cases Disconnected/Reconnected events appear due to network problems or Pulsoid servers rebalancing. These are rare events but at the same time, they must be handled properly to achieve best user experience. By default, PulsoidWebsocket does graceful reconnect under the hood. Default reconnection strategy is pretty aggressive - up to 24 hours for Pulsoid to become live. Also, you can customize reconnection strategy using these parameters.

  • Online/Offline events describe the state of heart rate streaming. Online event is emitted for the first received heart rate event. Offline event is emitted in case where there was no heart rate data input for 30 seconds. Therefore, these events can be used to communicate to the user that there is no heart rate data.

To learn more about events check out our documentation for pulsoid/socket.


Also, we created a self-contained plain HTML example of how pulsoid/socket library can be used on your website. Hosted demo is available here.


Links: HTML demo Pulsoid Socket library documentation Pulsoid Socket npm package Pulsoid API documentation Discord Twitter



39 views
Recent Posts
bottom of page