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

# Stickers

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

The player distinguishes different types of stickers interactions. 

* [Activate](/developers/guides/player-communication/message-api-reference/stickers/stickers-activate.md) — The sticker activation timer has started
* [Click](/developers/guides/player-communication/message-api-reference/stickers/stickers-click.md) — The sticker was clicked by a user
* [Expire](/developers/guides/player-communication/message-api-reference/stickers/stickers-expire.md) — The sticker has expired
* [Impression](/developers/guides/player-communication/message-api-reference/stickers/stickers-impression.md) — The sticker becomes visible in a user's viewport
* [Publish](/developers/guides/player-communication/message-api-reference/stickers/stickers-publish.md) — The sticker was published by a creator or moderator
* [Unlock](/developers/guides/player-communication/message-api-reference/stickers/stickers-unlock.md) — The sticker's activation timer is complete
* [Unpublish](/developers/guides/player-communication/message-api-reference/stickers/stickers-unpublish.md) — The sticker was unpublished by a creator or moderator
* [Update](/developers/guides/player-communication/message-api-reference/stickers/stickers-update.md) — Poll details have been updated
* [Voucher Claim](/developers/guides/player-communication/message-api-reference/stickers/stickers-voucher-claim.md) — The voucher code of a voucher sticker has been claimed by a user

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 Sticker 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>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>stickerActionTarget</code></td><td valign="top"><pre><code>StickerActionTarget
</code></pre><p>Optional.</p></td><td valign="top">The <code>stickerActionTarget</code> property represents the (localized) action to be executed when a user interacts with a UI element. It can be an identifier, a structured JSON payload, or a URL that opens in a new tab.<br><br>Refer to <a href="#stickeractiontarge">StickerActionTarget</a> for detailed information.</td></tr><tr><td valign="top"><code>stickerActivationTimerDurationInSec</code></td><td valign="top"><pre><code>number
</code></pre><p>Required.</p></td><td valign="top">The <code>stickerActivationTimerDurationInSec</code> property defines the length of the activation timer in seconds. If no activation timer is set for the sticker, the value is <code>0</code>.</td></tr><tr><td valign="top"><code>stickerActivationTimerIsActive</code></td><td valign="top"><pre><code>boolean
</code></pre><p>Required.</p></td><td valign="top">The <code>stickerActivationTimerIsActive</code> property indicates, whether the sticker's activation timer is currently running.</td></tr><tr><td valign="top"><code>stickerActivationTimerIsCompleted</code></td><td valign="top"><pre><code>boolean
</code></pre><p>Required.</p></td><td valign="top">The <code>stickerActivationTimerIsCompleted</code> property indicates, whether the sticker's activation timer is complete.</td></tr><tr><td valign="top"><code>stickerActivationTimerStartedAt</code></td><td valign="top"><pre><code>string
</code></pre><p>Optional.</p></td><td valign="top">The <code>stickerActivationTimerStartedAt</code> property represents the timestamp when the activation timer of the sticker was started — represented in ISO 8601 format.</td></tr><tr><td valign="top"><code>stickerDetails</code></td><td valign="top"><pre><code>StickerDetails
</code></pre><p>Optional.</p></td><td valign="top">The <code>stickerDetails</code> property represents the corresponding details object containing relevant information. The structure of this object varies depending on the <code>stickerType</code>.<br><br>Refer to <a href="#stickerdetails">StickerDetails</a> for detailed information.</td></tr><tr><td valign="top"><code>stickerExpiryTimerDurationInSec</code></td><td valign="top"><pre><code>number
</code></pre><p>Required.</p></td><td valign="top">The <code>stickerExpiryTimerDurationInSec</code> property defines the length of the expiry timer in seconds. If no expiry timer is set for the sticker, the value is <code>0</code>.</td></tr><tr><td valign="top"><code>stickerExpiryTimerIsActive</code></td><td valign="top"><pre><code>boolean
</code></pre><p>Required.</p></td><td valign="top">The <code>stickerExpiryTimerIsActive</code> property indicates, whether the sticker's expiry timer is currently running.</td></tr><tr><td valign="top"><code>stickerExpiryTimerStartedAt</code></td><td valign="top"><pre><code>string
</code></pre><p>Optional.</p></td><td valign="top">The <code>stickerExpiryTimerStartedAt</code> property represents the timestamp when the expiry timer of the sticker was started — represented in ISO 8601 format.</td></tr><tr><td valign="top"><code>stickerId</code></td><td valign="top"><pre><code>string
</code></pre><p>Required.</p></td><td valign="top">The <code>stickerId</code> property represents the unique sticker identifier.</td></tr><tr><td valign="top"><code>stickerIsExpired</code></td><td valign="top"><pre><code>boolean
</code></pre><p>Required.</p></td><td valign="top">The <code>stickerIsExpired</code> property indicates, whether the sticker has expired.</td></tr><tr><td valign="top"><code>stickerIsUnlocked</code></td><td valign="top"><pre><code>boolean
</code></pre><p>Required.</p></td><td valign="top">The <code>stickerIsUnlocked</code> property indicates, whether the sticker is unlocked. Either when the activation timer is not set or has completed AND the sticker has not expired.</td></tr><tr><td valign="top"><code>stickerType</code></td><td valign="top"><pre><code>Enum
</code></pre><p>Required.</p></td><td valign="top"><p>The <code>stickerType</code> property represents the type of sticker being used.<br></p><p><strong>Allowed Values:</strong></p><ul><li><code>alert</code> – Displays an informational or warning alert.</li><li><code>poll</code> – Represents a poll for collecting user votes.</li><li><code>product</code> – Showcases a product-related sticker.</li><li><code>voucher</code> – Represents a discount or promotional voucher sticker.</li></ul></td></tr></tbody></table>

***

### Type Definition

```typescript
interface StickerMessage extends Omit<
  Message,
  'messageType' | 'sender'
> {
  mediaItemId: string;
  mediaItemType: MediaItemType;
  messageType:
    | 'lsc:sticker:activate'
    | 'lsc:sticker:click'
    | 'lsc:sticker:expire'
    | 'lsc:sticker:impression'
    | 'lsc:sticker:publish'
    | 'lsc:sticker:unlock'
    | 'lsc:sticker:unpublish'
    | 'lsc:sticker:update'
    | 'lsc:sticker:voucher:claim';
  progress: MediaProgress;
  stickerActionTarget?: StickerActionTarget;
  stickerActivationTimerDurationInSec: number;
  stickerActivationTimerIsActive: boolean;
  stickerActivationTimerIsCompleted: boolean;
  stickerActivationTimerStartedAt?: string;
  stickerDetails: StickerDetails;
  stickerExpiryTimerDurationInSec: number;
  stickerExpiryTimerIsActive: boolean;
  stickerExpiryTimerStartedAt?: string;
  stickerId: string;
  stickerIsExpired: boolean;
  stickerIsUnlocked: boolean;
  stickerType: 'alert' | 'poll' | 'product' | 'voucher';
  sender: 'LiSA';
}
```

#### `StickerActionTarget`

```typescript
type StickerActionTarget = Record<string, unknown> | string;
```

The Sticker Action supports three different use cases:

* Identifier (String) — Represents an action or event that the host app / environment can interpret and execute.&#x20;
* Structured Data (Object) — For more complex action definitions the action target contains an object structure.

#### `StickerDetails`

The `StickersDetails` type defines the corresponding details for each sticker based on its type.

{% tabs %}
{% tab title="Alert" %}
The **Alert** sticker does not contain any specific details, so the `stickerDetails` value is always an empty object.
{% endtab %}

{% tab title="Poll" %}
The **Poll** sticker does not contain any specific details, so the `stickerDetails` value is always an empty object.
{% endtab %}

{% tab title="Product" %}
The **Product** sticker specifies the essential product properties and CTA behavior:

***

**`ctaBehavior`** — {Enum} Optional. \
Indicates whether upon user interaction the product is added to card directly, or its PDP is opened. Default: `view`

***

**`productBrand`** — {string} Optional.\
The name of the product's brand.

***

**`productCurrency`** — {CurrencyCode} Optional.\
The currency code associated with the product price.

***

**`productId`** — {string} Optional.\
Represents the internal LiSA product identifier.

* This ID is unique within the LiSA system and is used for internal product tracking.
* **Note:** Do not confuse this with `productReference`, which may refer to an external or merchant-specific product identifier.

***

**`productOriginalPrice`** — {number} Optional.\
Represents the original price of the product, if the product price is discounted.

***

**`productPrice`** — {number} Optional.\
Represents the effective price of the product, which may be either the original price or the sale price, depending on availability.

***

**`productReference`** — {string} Optional.\
Represents an external or merchant-specific identifier for the product.

* This ID is provided by the merchant or host system and may differ from the internal `productId`.
* It is used to reference the product in external systems, such as e-commerce platforms or inventory databases.

***

**`productTitle`** — {string} Optional.\
Represents the localized name of the product.

***

**`variantId`** — {string} Optional.\
&#x20;Represents the internal LiSA product variant identifier.

* This ID is unique within the LiSA system and is used for internal product variant tracking.
* **Note:** Do not confuse this with `variantReference`, which may refer to an external or merchant-specific product variant identifier.

***

**`variantReference`** — {string} Optional.\
&#x20;Represents an external or merchant-specific identifier for the product variant.

* This ID is provided by the merchant or host system and may differ from the internal `variantId`.
* It is used to reference the product variant in external systems, such as e-commerce platform

***

```typescript
interface ProductStickerDetails {
  ctaBehavior?: 'addToCart' | 'view';
  productBrand?: string;
  productCurrency?: string;
  productId?: string;
  productOriginalPrice?: number;
  productPrice?: number;
  productReference?: string;
  productTitle?: string;
  variantId?: string;
  variantReference?: string;
}
```

{% endtab %}

{% tab title="Voucher" %}
The **Voucher** sticker specifies the voucher code and redemption CTA behavior:

***

**`ctaBehavior`** — {Enum} Optional.\
Indicates whether upon user interaction the voucher code is added to card directly, or copied to clipboard. Default: `clipboard`&#x20;

***

**`voucherCode`** — {string} Optional.

***

**`voucherDiscountType`** — {Enum} Optional.\
Indicates whether the voucher discount value is applied as a fixed value or percentage value.

***

**`voucherDiscountLabel`** — {string} Optional.\
Determines how the voucher discount should be rendered.

***

**`voucherDiscountValue`** — {number} Optional.\
The numeric discount value.

***

**`voucherExpiresAt`** — {string} Optional.\
The date, when the voucher code expires. Represented in form of an ISO 8601 timestamp.

***

```typescript
interface VoucherStickerDetails {
  ctaBehavior?: 'addToCart' | 'clipboard';
  voucherCode?: string;
  voucherDiscountLabel?: string;
  voucherDiscountType?: 'fixed' | 'percentage';
  voucherDiscountValue?: number;
  voucherExpiresAt?: string;
}
```

{% endtab %}
{% endtabs %}

***