Message API Reference

Documentation Update in Progress

We are currently revisiting and updating this section of our documentation to ensure it provides the most accurate and helpful information. Some content may be incomplete or outdated during this process. Additionally, we are in the process of adding the Message API reference for Player Version 2.

Thank you for your patience! If you have any immediate questions, please don’t hesitate to contact our support team.

All LiSA Player messages conform to the Message interface. This interface includes details about the specific type of event, along with sender information and optional recipient information.

Properties

Name	Type	Description
clockDriftInMs	Number Required.	The clockDriftInMs field represents the calculated drift between the client's local clock and the server's UTC time. It is measured in milliseconds (ms). Definition Clock drift is the difference between the client's perceived current time and the expected local time derived from the server's UTC timestamp. Interpretation Positive value → The client clock is behind UTC (i.e., it is running slow). Negative value → The client clock is ahead of UTC (i.e., it is running fast). Zero → The client clock is perfectly in sync with the server time.
messageId	String Optional.	The messageId property is used to acknowledge the receipt of messages by the Player. This is particularly important for messages that require confirmation to ensure they are reliably received and not lost.
messageType	String Required.	The messageType property specifies the distinct type of message.
recipient	String Required for messages sent to the LiSA Player.	The distinct recipient identifier, specifying the receiver of this message. LiSA Player only accepts and processes message with value LiSA. LiSA Player omits this property, when sending messages.
sender	String Required.	The distinct sender identifier, specifying the origin of this message. LiSA Player uses fixed value LiSA, when sending messages.

Legacy Properties

If your integration uses LiSA Player Version 1, none of the properties described above will be available.

For LiSA Player Version 2, legacy properties can be ignored.

Name	Type	Description
action	String Required.	The distinct action representing the messages intent. ⚠️ Please use messageType instead.
additional	Object Optional.	Map of additional message attributes. ⚠️ Please use specific message attributes instead.
target	String Required.	The distinct target addressing the scope of this message. ⚠️ Please use messageType instead.

---

Type Definition

interface Message {
  clockDriftInMs: number;
  messageId?: string;
  messageType: string;
  recipient?: 'LiSA';
  sender: string;

  // Legacy LiSA Player V1 attributes for backwards compatibility. 

  action: string;
  additional?: Record<string, unknown>;
  target: string;
}