> 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/products.md).

# Products

The LiSA Player sends messages in response to various user interactions with products.

The player distinguishes different types of product interactions. 

* [Add to Cart](/developers/guides/player-communication/message-api-reference/products/products-add-to-cart.md)
* [Add to Wishlist](/developers/guides/player-communication/message-api-reference/products/products-add-to-wishlist.md)
* [Click](/developers/guides/player-communication/message-api-reference/products/products-click.md)
* [Close Product List](/developers/guides/player-communication/message-api-reference/products/products-close-product-list.md)
* [Emoji](/developers/guides/player-communication/message-api-reference/products/products-emoji.md)
* [Emoji State Update](/developers/guides/player-communication/message-api-reference/products/products-emoji-state-update.md)
* [Impression](/developers/guides/products.md)
* [Open Product List](/developers/guides/player-communication/message-api-reference/products/products-open-product-list.md)

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 Product Interaction message includes the following additional properties:

<table><thead><tr><th width="220" valign="top">Name</th><th width="175" 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">The <code>messageType</code> property specifies the distinct type of message.</td></tr><tr><td valign="top"><code>productBrand</code></td><td valign="top"><pre><code>String
</code></pre><p>Optional.</p></td><td valign="top">The <code>productBrand</code> property represents the localized name of the product's brand, if available.</td></tr><tr><td valign="top"><code>productCurrency</code></td><td valign="top"><pre><code>String
</code></pre><p>Optional.</p></td><td valign="top">The <code>productCurrency</code> property specifies the currency code (ISO 4217, 3-letter format) of the product price.</td></tr><tr><td valign="top"><code>productId</code></td><td valign="top"><pre><code>String
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>productId</code> property is the internal LiSA product identifier.</p><ul><li>This ID is unique within the LiSA system and is used for internal product tracking.</li><li><strong>Note:</strong> Do not confuse this with <code>productReference</code>, which may refer to an external or merchant-specific product identifier.</li></ul></td></tr><tr><td valign="top"><code>productOriginalPrice</code></td><td valign="top"><pre><code>Number
</code></pre><p>Optional.</p></td><td valign="top">The <code>productOriginalPrice</code> property represents the original price of the product, if the product price is discounted.</td></tr><tr><td valign="top"><code>productPrice</code></td><td valign="top"><pre><code>Number
</code></pre><p>Optional.</p></td><td valign="top">The <code>productPrice</code> property represents the effective price of the product, which may be either the original price or the sale price, depending on availability.</td></tr><tr><td valign="top"><code>productReference</code></td><td valign="top"><pre><code>String
</code></pre><p>Optional.</p></td><td valign="top"><p>The <code>productReference</code> property represents an external or merchant-specific identifier for the product.</p><ul><li>This ID is provided by the merchant or host system and may differ from the internal <code>productId</code>.</li><li>It is used to reference the product in external systems, such as e-commerce platforms or inventory databases.</li></ul></td></tr><tr><td valign="top"><code>productTitle</code></td><td valign="top"><pre><code>String
</code></pre><p>Required.</p></td><td valign="top">The <code>productTitle</code> property represents the localized name of the product.</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>variantId</code></td><td valign="top"><pre><code>String
</code></pre><p>Optional.</p></td><td valign="top"><p></p><p>The <code>variantId</code> property is the internal LiSA product variant identifier.</p><ul><li>This ID is unique within the LiSA system and is used for internal product variant tracking.</li><li><strong>Note:</strong> Do not confuse this with <code>variantReference</code>, which may refer to an external or merchant-specific product variant identifier.</li></ul></td></tr><tr><td valign="top"><code>variantReference</code></td><td valign="top"><pre><code>String
</code></pre><p>Optional.</p></td><td valign="top"><p>The <code>variantReference</code> property represents an external or merchant-specific identifier for the product variant.</p><ul><li>This ID is provided by the merchant or host system and may differ from the internal <code>variantId</code>.</li><li>It is used to reference the product variant in external systems, such as e-commerce platforms or inventory databases.</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">The distinct type of product interaction.<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>AdditionalProductData
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>additional</code> property contains metadata related to product interactions.</p><p><br>Please refer to <a href="#additionalproductdata-legacy">AdditionalProductData</a> for detailed information.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Please use dedicated product-related properties instead.</p></td></tr><tr><td valign="top"><code>first</code></td><td valign="top"><pre><code>Boolean
</code></pre><p>Required.</p></td><td valign="top">The <code>first</code> property indicates, whether the message represents the first product interaction of a distinct type per product in the current visitor's session.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> This property is no longer supported in Player Version 2.</td></tr><tr><td valign="top"><code>item</code></td><td valign="top"><pre><code>ProductItem
</code></pre><p>Required.</p></td><td valign="top">The <code>item</code> property describes a limited set of product properties relevant to a specific product interaction.<br><br>Please refer to <a href="#productitem">ProductItem</a> for detailed information.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Please use dedicated product-related properties 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">The distinct target of product interaction.<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 ProductMessage extends Omit<
  Message,
  'messageType' | 'sender'
> {
  mediaItemId: string;
  mediaItemType: MediaItemType;
  messageType:
    | 'lsc:product:add-to-cart'
    | 'lsc:product:add-to-wishlist'
    | 'lsc:product:click'
    | 'lsc:product:emoji'
    | 'lsc:product:impresssion';
  productBrand?: string;
  productCurrency?: string;
  productId: string;
  productOriginalPrice?: number;
  productPrice?: number;
  productReference?: string;
  productTitle: string;
  variantId?: string;
  variantReference?: string;
  progress: MediaProgress;
  sender: 'LiSA';
}
```

***

#### `AdditionalProductData` — Legacy

In addition to the standard [Additional Data](/developers/guides/player-communication/message-api-reference/shared-legacy-message-properties.md#additional-data) properties, the `additional` property contains metadata related to product interactions.

<table><thead><tr><th width="243" valign="top">Name</th><th width="175" 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>Optional.</p></td><td valign="top">The <code>action</code> property represents the action target of a carousel item interaction. Depending on the use-case it can either be a URL or a serialized JSON object, containing parameters required to execute upon the interaction in the host app / environment.</td></tr><tr><td valign="top"><code>id</code></td><td valign="top"><pre><code>String
</code></pre><p>Optional.</p></td><td valign="top">The <code>id</code> property represents the unique identifier of the product as specified in the customer's e-commerce system.</td></tr><tr><td valign="top"><code>variantId</code></td><td valign="top"><pre><code>String
</code></pre><p>Optional.</p></td><td valign="top">The <code>variantId</code> property represents the unique identifier of the selected product variant as specified in the customer's e-commerce system.</td></tr></tbody></table>

<pre class="language-typescript"><code class="lang-typescript"><strong>interface AdditionalProductData extends AdditionalData {
</strong>  action?: string;
  id?: string;
  variantId?: string;
}
</code></pre>

#### `ProductItem` — Legacy

The `ProductItem` property describes a limited set of product properties relevant to a specific product interaction.

<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>data</code></td><td valign="top"><pre><code>ProductItemData
</code></pre><p>Required.</p></td><td valign="top">The distinct type of product interaction.<br><br>Please refer to ProductItemData for detailed information.</td></tr><tr><td valign="top"><code>id</code></td><td valign="top"><pre><code>String
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>id</code> property is the internal LiSA product identifier.</p><ul><li>This ID is unique within the LiSA system and is used for internal product tracking.</li><li><strong>Note:</strong> Do not confuse this with <code>data.origin.id</code>, which may refer to an external or merchant-specific product identifier.</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>product</code></td></tr></tbody></table>

<pre class="language-typescript"><code class="lang-typescript"><strong>interface ProductItem {
</strong>  data: ProductItemData;
  id: string;
  type: 'product';
}
</code></pre>

#### `ProductItemData` — Legacy

{% hint style="info" %}
The `ProductItemData` object contains additional properties that are generally non-essential for most use cases.

* As these are legacy properties, we do not recommend using them.
* Instead, we encourage relying on the distinct properties available in the **Product Interaction** messages for better clarity and consistency.
  {% 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>origin</code></td><td valign="top"><pre><code>ProductOrigin
</code></pre><p>Optional.</p></td><td valign="top">The <code>productOrigin</code> property is an object that specifies essential details about the product's origin within the merchant's e-commerce system.<br><br>Please refer to <a href="#productorigin-legacy">ProductOrigin</a> for detailed information.</td></tr></tbody></table>

<pre class="language-typescript"><code class="lang-typescript"><strong>interface ProductItemData {
</strong>  origin?: ProductOrigin;
}
</code></pre>

#### `ProductOrigin` — Legacy

<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>Optional.</p></td><td valign="top"><p>The <code>id</code> property represents an external or merchant-specific identifier for the product.</p><ul><li>This ID is provided by the merchant or host system and may differ from the LiSA-internal product identifier.</li></ul></td></tr></tbody></table>

```typescript
interface ProductOrigin {
  id?: string;
}
```