Subscription Flow

This is a step-by-step guide to connecting a subscriber — a device, or an application acting on its behalf — to the Haptics server and receiving signals. It assumes the device is already linked to a Melody account.

1. Obtain an authentication token

Request a short-lived authentication token and server endpoint from the Subscriber Auth API (see the API Reference). Use the Device Subscriber endpoint for a device connecting directly, or the App Subscriber endpoint when an intermediate application connects on the device’s behalf.

curl -X POST -H 'Content-Type: application/json' \
  https://api.getmelody.io/api/haptics/auth/subscriber/device \
  --data '{"subscription_id":"123-4567-890","pairing_token":"eyJ0eX..."}'

The response contains the WebSocket endpoint and a token to connect with:

{
  "ws_endpoint": "wss://ws.endpoint/haptics",
  "ws_proxy_endpoint": "wss://ws.endpoint/haptics",
  "token": "eyJ0eX..."
}

ws_proxy_endpoint is deprecated — use ws_endpoint.

2. Connect and authenticate

Connect to the Haptics 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://ws.endpoint/haptics", nil)

Send the authentication frame:

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

bytes, err := proto.Marshal(authProto)

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

err = authFrame.WriteFrame(c.stream)

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 and manage stream quality.

for {
	dataFrame, err := protocol.ReadNextFrame(c.stream)

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

	// Adjust internal algorithms using connection info
	case entities.FrameType_CONNECTION_INFO:
		// TODO: your logic

	// Process actual signal events
	case entities.FrameType_SIGNAL:
		// TODO: your logic

	default:
	}
}

This connects a subscriber to the Haptics server, authenticates it, and receives signals for further processing. To transmit signals instead, see the Publication Flow.

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