> For the complete documentation index, see [llms.txt](https://docs.hello-lisa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference/comments-join.md).

# Comments — Join

The LiSA Player generates a message whenever a visitor joins the chat in a live stream.

This message is sent by the LiSA Player to the host app / environment.

### Properties

Along with all standard [Message properties](/developers/guides/player-communication/message-api-reference.md#properties), a Join message includes the following additional properties:

<table><thead><tr><th width="240" valign="top">Name</th><th width="196" valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>mediaItemId</code></td><td valign="top"><pre><code>string
</code></pre><p>Required.</p></td><td valign="top">The <code>mediaItemId</code> property uniquely identifies the Media Item from which this message originates.</td></tr><tr><td valign="top"><code>mediaItemType</code></td><td valign="top"><pre><code>MediaItemType
</code></pre><p>Required.</p></td><td valign="top">The <code>mediaItemType</code> property specifies the type of Media Item from which this message originates.<br><br>Refer to <a href="/pages/TzMvWg0wtnzBMpFfvyoN#media-item-type"><code>MediaItemType</code></a> for detailed information.</td></tr><tr><td valign="top"><code>messageType</code></td><td valign="top"><pre><code>Literal
</code></pre><p>Required.</p></td><td valign="top"><code>lsc:comments:audience:join</code></td></tr><tr><td valign="top"><code>progress</code></td><td valign="top"><pre><code>MediaProgress
</code></pre><p>Required.</p></td><td valign="top">The <code>progress</code> property is an object that holds additional metadata related to the media playback progress of the current media item.<br><br>Please refer to <a href="/pages/rMD8D7mCXjBlgew5J7ms#media-progress"><code>MediaProgress</code></a> for detailed information.</td></tr><tr><td valign="top"><code>visitorAvatarUrl</code></td><td valign="top"><pre><code>String
</code></pre><p>Optional.</p></td><td valign="top">The <code>visitorAvatarUrl</code> property is used to provide a URL pointing to an image that represents the visitor's avatar.</td></tr><tr><td valign="top"><code>visitorExternalId</code></td><td valign="top"><pre><code>String
</code></pre><p>Optional.</p></td><td valign="top">The <code>visitorExternalId</code> property specifies the visitor's ID as provided in the <a href="/pages/KydRNTm7c6nhoQcchsdu">Pass User Context</a> message.</td></tr><tr><td valign="top"><code>visitorName</code></td><td valign="top"><pre><code>String
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>visitorName</code> property represents the visitor's display name.</p><ul><li>If provided in the <a href="/pages/KydRNTm7c6nhoQcchsdu">Pass User Context</a> message, it reflects the name assigned by the host app.</li><li>If not included, it contains the username the visitor chose when joining the chat.</li></ul></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="190" 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"><code>chat-join</code><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>target</code></td><td valign="top"><pre><code>Literal
</code></pre><p>Required.</p></td><td valign="top"><code>show.engage</code><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>user</code></td><td valign="top"><pre><code>User
</code></pre><p>Required.</p></td><td valign="top">The <code>user</code> property specifies the essential user properties.<br><br>Please refer to <a href="#user">User</a> for detailed information.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Please use <code>visitor*</code> properties instead.</td></tr></tbody></table>

***

### Type Definition

```typescript
interface CommentsJoinMessage extends Omit<
  Message,
  'messageType' | 'sender'
> {
  mediaItemId: string;
  mediaItemType: MediaItemType;
  messageType: 'lsc:cart:view';
  progress: MediaProgress;
  visitorAvatarUrl?: string;
  visitorExternalId?: string;
  visitorName: string;
}
```

#### `User`

<table><thead><tr><th width="197" valign="top">Name</th><th width="190" valign="top">Type</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>id</code></td><td valign="top"><pre><code>String
</code></pre><p>Required.</p></td><td valign="top">The <code>visitorExternalId</code> property specifies the visitor's ID as provided in the <a href="/pages/KydRNTm7c6nhoQcchsdu">Pass User Context</a> message.</td></tr><tr><td valign="top"><code>name</code></td><td valign="top"><pre><code>Literal
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>visitorName</code> property represents the visitor's display name.</p><ul><li>If provided in the <a href="/pages/KydRNTm7c6nhoQcchsdu">Pass User Context</a> message, it reflects the name assigned by the host app.</li><li>If not included, it contains the username the visitor chose when joining the chat.</li></ul></td></tr><tr><td valign="top"><code>type</code></td><td valign="top"><pre><code>Literal
</code></pre><p>Required.</p></td><td valign="top"><code>viewer</code></td></tr></tbody></table>

```typescript
interface User {
  id: string;
  name: string;
  type: 'viewer';
}
```

***

### Examples

```json
{
  "clockDriftInMs": 0,
  "mediaItemId": "9f333331-45cb-4289-8bcd-9023c1871111",
  "mediaItemType": "live",
  "messageType": "lsc:comments:audience:join",
  "progress": {
    "bufferedTimeInMs": 636036,
    "currentTimeInMs": 619609,
    "durationInMs": 4616000,
    "elapsedTimeInMs": 22761,
    "isLive": true,
    "isPlaying": true,
    "skipTimeInMs": 600000,
    "visitorDwellTimeInMs": 23882
  },
  "sender": "LiSA",
  "visitorAvatarUrl": "https://my-cdn.com/path/to/image.jpg",
  "visitorExternalId": "65cf573a-8c51-4b89-b2da-3d79b35fcf1b",
  "visitorName": "Jane Doe",
  
  "action": "chat-join",
  "target": "show.engage",
  "user": {
    "id": "65cf573a-8c51-4b89-b2da-3d79b35fcf1b",
    "name": "Jane Doe",
    "type": "viewer"
  }
}
```