# Message API Reference

{% hint style="warning" %}
**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.
{% endhint %}

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

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

#### Legacy Properties

{% hint style="warning" %}
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.
{% endhint %}

<table><thead><tr><th width="197" valign="top">Name</th><th width="169" valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>action</code></td><td valign="top"><pre><code>String
</code></pre><p>Required.</p></td><td valign="top">The distinct action representing the messages intent.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Please use <code>messageType</code> instead.</td></tr><tr><td valign="top"><code>additional</code></td><td valign="top"><pre><code>Object
</code></pre><p>Optional.</p></td><td valign="top">Map of additional message attributes.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Please use specific message attributes instead.</td></tr><tr><td valign="top"><code>target</code></td><td valign="top"><pre><code>String
</code></pre><p>Required.</p></td><td valign="top">The distinct target addressing the scope of this message.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Please use <code>messageType</code> instead.</td></tr></tbody></table>

***

### Type Definition

```typescript
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;
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.