Subscription Flow

Connect a subscriber — a device, or an application acting for it — to the Melody server and receive signals. The device must already be linked to a Melody account.

1. Obtain an authentication token

This page describes the flow a device performs, not an application. The credential below, the device token, is issued to the device itself: firmware exchanges the system token it received during factory activation for one at POST /api/haptics/device/device_token. If you are building an application that controls a device, you do not handle it — use the session token and X-Device-Key described in Organization access.

Request a short-lived session token and server endpoint from the subscriber auth endpoint. The request carries no body: the device authenticates with its device token in the Authorization header, and the subscription is resolved from that token.

curl -X POST https://api.getmelody.io/api/haptics/auth/subscriber/device \
  -H 'Authorization: Bearer <DEVICE_TOKEN>'

The token must be a device-scoped key; anything else is rejected with 401. The response contains the WebSocket endpoint and a token to connect with:

{
  "ws_endpoint": "wss://api.getmelody.io/api/haptics/ws",
  "ws_proxy_endpoint": "wss://api.getmelody.io/api/haptics/ws",
  "token": "eyJ0eX..."
}

ws_proxy_endpoint is deprecated — use ws_endpoint.

2. Connect and authenticate

Connect to the Melody server over WebSocket and send a HapticFrame carrying a Protobuf Auth message. Open the connection:

dialer := websocket.Dialer{
	TLSClientConfig: &tls.Config{},
}

conn, _, err := dialer.Dial("wss://api.getmelody.io/api/haptics/ws", nil)

Send the authentication frame:

authProto := &entities.Auth{
	SessionToken: token, // token from step 1
}

bytes, err := proto.Marshal(authProto)

authFrame := &protocol.HapticFrame{
	Type: entities.FrameType_SUBSCRIPTION,
	Data: bytes,
}

err = authFrame.WriteFrame(conn.UnderlyingConn())

3. Receive signals

Read frames from the stream and dispatch on the frame type. Always echo TIME_SYNC frames back so the server can measure round-trip latency.

for {
	dataFrame, err := protocol.ReadNextFrame(conn.UnderlyingConn())

	switch dataFrame.Type {
	// Echo the system TIME_SYNC event back
	case entities.FrameType_TIME_SYNC:
		dataFrame.WriteFrame(conn.UnderlyingConn())

	// Latency and stream details from the server
	case entities.FrameType_CONNECTION_INFO:
		info, err := extension.NewConnectionInfoFromBytes(dataFrame.Data)
		// use info.ServerLatencyMs to adjust your timeline

	// A batch of motion points
	case entities.FrameType_SIGNAL:
		signal, err := extension.NewHPSSignalFromBytes(dataFrame.Data)
		// drive your UI or forward the points

	default:
	}
}

That is the whole subscriber flow: connect, authenticate, read signals.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

Subscription Flow

1. Obtain an authentication token

2. Connect and authenticate

3. Receive signals

​1. Obtain an authentication token

​2. Connect and authenticate

​3. Receive signals

1. Obtain an authentication token

2. Connect and authenticate

3. Receive signals