# 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](https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference/products/products-add-to-cart)
* [Add to Wishlist](https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference/products/products-add-to-wishlist)
* [Click](https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference/products/products-click)
* [Close Product List](https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference/products/products-close-product-list)
* [Emoji](https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference/products/products-emoji)
* [Emoji State Update](https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference/products/products-emoji-state-update)
* [Impression](https://docs.hello-lisa.com/developers/guides/products)
* [Open Product List](https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference/products/products-open-product-list)

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

### Properties

Along with all standard [Message properties](https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference/..#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="../media-item#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="../media#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](https://docs.hello-lisa.com/developers/guides/player-communication/shared-legacy-message-properties#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;
}
```


---

# 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/products.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.