OTP via WebSocket

This is what the device does over its own WebSocket connection. An application asks for an OTP with POST /device/otp/generate instead — see Organization access.

A Melody device can request an OTP over its active WebSocket connection rather than making a separate HTTP call.

Frame Types

Frame Type	Value	Direction	Protobuf Message
`OTP_REQUEST`	`19`	Device → Server	`OTPRequest`
`OTP_RESPONSE`	`20`	Server → Device	`OTPResponse`

Message Definitions

OTPRequest (device → server):

message OTPRequest {
  bool reserved = 1; // reserved for future fields (e.g. scope)
}

OTPResponse (server → device):

message OTPResponse {
  string otp = 1;           // The OTP code
  uint64 expires_at_ms = 2; // Expiration timestamp in milliseconds (Unix)
  string error = 3;         // Non-empty if the request failed
}

Flow

Device sends an OTP_REQUEST frame with a serialized (empty) OTPRequest message over the existing WebSocket connection.
Server generates the OTP and replies with an OTP_RESPONSE frame on the same connection.
If generation fails, error is non-empty — otp should be ignored in this case.

Code Example

// --- Request ---

otpReq := &entities.OTPRequest{}
data, err := proto.Marshal(otpReq)
if err != nil {
    return err
}

frame := protocol.NewHapticFrame(entities.FrameType_OTP_REQUEST, data)
if err := frame.WriteFrame(stream); err != nil {
    return err
}

// --- Response ---

respFrame, err := protocol.ReadNextFrame(stream)
if err != nil {
    return err
}

if respFrame.Type != entities.FrameType_OTP_RESPONSE {
    return fmt.Errorf("unexpected frame type: %v", respFrame.Type)
}

otpResp := &entities.OTPResponse{}
if err := proto.Unmarshal(respFrame.Data, otpResp); err != nil {
    return err
}

if otpResp.Error != "" {
    return fmt.Errorf("OTP generation failed: %s", otpResp.Error)
}

fmt.Printf("OTP: %s, expires at: %d ms\n", otpResp.Otp, otpResp.ExpiresAtMs)

Notes

The OTP is scoped to the requesting device’s connection — it is not broadcast to other subscribers.
The server answers within 10 seconds, or the request times out.
POST /device/otp/generate remains available as an alternative for obtaining an OTP without an active WebSocket connection.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

OTP via WebSocket

Frame Types

Message Definitions

Flow

Code Example

Notes

​Frame Types

​Message Definitions

​Flow

​Code Example

​Notes

Frame Types

Message Definitions

Flow

Code Example

Notes