> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/products/gamification-basics/avatars.md).

# Avatars

### Overview

Avatars let users personalize how they appear in the gamification widget. With Smartico, you can create avatars, show them in the UI, and give them as rewards through features like Missions, Tournaments, Mini-games, and more.

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-3e0546713f13db9e003a22f63d77639c2507eed3%2FProperty%201%3DDefault.png?alt=media" alt=""><figcaption><p>GF: Customize your avatar</p></figcaption></figure>

### How it works?

Once Avatars are enabled you can manage them from `BO → Gamification → Avatars.`

Each avatar can be:

* **Free** - Available to all users
* **Reward-based** - Given as a reward (from Missions, Tournaments, Mini-games, Store, etc.)

{% hint style="info" %}
**Note:** To enable Avatars V2, please contact your Success Manager.

⚠️ Please note that **Avatars V2** is a free feature, while **Avatar Customization** is available as a paid add-on.
{% endhint %}

#### Enabling Avatars V2

If you are currently using legacy avatars, or you are a new client who has not yet configured any avatars, and you want to enable and test Avatars V2, follow these steps in Label settings:

* Ask your Success Manager to enable the Avatars V2 product
* Set the new avatars to be visible only for Test users: **Avatars V2: turn on for** = **Test users** (this ensures legacy avatars remain visible for real users while testing)
* Set avatar customization to be visible only for Test users: **Avatars V2: AI customization on for** = **Test users**
* Create your avatars and customizations and test them
* Once you’re ready, enable avatars and customization (optional) for **All users**

{% hint style="info" %}
**Note:** The default limit values are intended for testing and can be adjusted later. By default a label has 100 AI customizations per month for all players together (**Avatars V2: AI customizations per month, whole label**) and 50 per player per month (**Avatars V2: AI customizations per player per month**). A CRM Admin can change the per-player limit in **Label → Label, settings**; contact Smartico to raise the label limit.
{% endhint %}

#### Creating an Avatar

To create an avatar, go to the **Avatars** section in the BO and click the **Create** button.

<div><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-922631eb5cd9696ac894f7ea62731ec015fa047d%2FScreenshot_47.png?alt=media" alt=""><figcaption><p>BO: Avatars template - General section</p></figcaption></figure> <figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-09414a59562e9ee3ddd3674036f42231a98bcb10%2FScreenshot_48.png?alt=media" alt=""><figcaption><p>BO: Avatars template - Additional section</p></figcaption></figure></div>

When creating an avatar, you can:

* **Internal name** - The name of the avatar in the BO.
* **Set status (Active / Inactive)** - Inactive avatars are hidden from users.
* **Upload an image** - Upload the image for the avatar
* **Image specifications and AI generation** - Recommended avatar image size is 256×256 pixels in PNG, JPG or WebP format (at least 64×64 pixels). You can also generate avatar images directly in the Back-Office using the **Create** button of the image field (when AI image generation is enabled for your label).
* **Add a description** - Add a description for the avatar. For example, if the avatar is awarded through a mission, you can include a deep link to that specific mission.
* **Set as default avatar** - This avatar will be assigned to all users by default. If no default avatar is set, each user will be assigned a random avatar from the available “Free” avatars.
* **Assign avatar to** - Choose whether the avatar is freely available or must be earned as a reward
  * **Not assigned (Free)** → users can use it immediately
  * Reward-based (**Automation Rule**, **Campaign**, **Mission**, **Badge**, **Tournament**, **Raffle**, **Store** or **Mini-games**) → users must earn or purchase it

{% hint style="info" %}
**Note:** A Store item can sell one avatar or a pack of up to 50 avatars. The player pays the full price and receives the avatars they don't own yet. The item stays buyable after the player owns all of its avatars, so it is recommended to limit the item to a one-time lifetime purchase. You can also configure the Store item to be hidden once the purchase limit is reached. For full details on configuring Store item limits, see [Store](https://help.smartico.ai/welcome/products/gamification-basics/marketplace.md).
{% endhint %}

* **Set availability period** (optional) - Show the avatar only between specific dates. You can select whether the availability dates follow a fixed UTC time or the player’s local time zone. Available only for ‘Free’ avatars.
* **Show avatar before earned** - Available only for Reward-based Avatars (toggle Yes or No)
  * **Yes** (Show as Locked) - the avatar is visible to players but displayed as unavailable (grayed out)
  * **No** (Hide until earned) - the avatar remains hidden until it is unlocked through a mission, tournament, mini-game, etc..
* **Avatar priority** - Display order. Controls how avatars are ordered in the widget
* **Branding** (on labels with brand-level settings) - Set a different image and description for each brand

**Using Avatars as Rewards** - Avatars can be given to users through:

* Mission
* Badge
* Mission task
* Tournament
* Clan tournament
* Mini-game
* Store item
* Raffle
* Campaign reward
* Automation Rule reward

Each of these rewards can give one avatar or a set of up to 50 avatars.

#### Giving several avatars in one reward

Every reward that grants avatars can grant a set of avatars in one go: Automation Rules (realtime and scheduled), Campaign Journeys, Missions and Badges, mission tasks, Tournaments, Clan tournaments, Raffles, Mini-games (Spin & Win, Prize Drop, Lootbox, MatchX, Quiz) and Store items.

**How to set it up**

* In the activity, prize or store item, choose **Avatar(s)** as the type.
* In the **Avatar(s)** field, select the avatars. The list shows only avatars assigned to this kind of reward (for example, avatars assigned to "Automation rule" in an Automation Rule). Type to search by name.
* Click **Select all** to add every avatar in the list. The counter shows how many avatars are selected out of 50.
* Remove an avatar by clicking the × on its chip.

![BO: Avatar(s) field with two avatars selected, the Select All button and the 2 / 50 counter](https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2FrCedHAlRP8UCaYLLBt37%2Favatars-multi-picker-13304232-970029.png?alt=media)

The activity summary shows how many avatars the reward gives and their names, for example "Avatars (12): Lion, Tiger, Bear +9".

![BO: Activity Details of an Automation Rule that gives two avatars](https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2FiPFqZ1pdDslbuNr5Aegh%2Favatars-multi-summary-30e5653b-8665e2.png?alt=media)

**Rules**

* Up to 50 avatars per reward.
* Avatars the player already owns are skipped.
* Inactive, deleted and out-of-period avatars are skipped; the other avatars of the set are still granted.
* Players in the control group receive none of the avatars in the set.
* In Mini-games, Raffles and Tournaments, a prize with several avatars counts as one prize: winning it grants the whole set. Prize odds, stock and win counts stay per prize.
* Each granted avatar appears separately in reports and data exports.
* Rewards created before this change open with their avatar pre-selected and keep working as before.

{% hint style="success" %}
**Example: give each brand its own avatar pack.** Create one Automation Rule per brand with the trigger on registration, a segment filtered by brand, and one Avatar(s) activity holding that brand's pack. New players of each brand get their brand's avatars automatically.
{% endhint %}

### Avatar Customization

Users can customize their avatars using predefined options (powered by AI), such as adding accessories or changing styles.

* Customizations are configured by the operator in the BO
* From the user’s perspective, each customization is paid (e.g., using points, gems, etc.)
* Each time a user applies a customization, a new variation is generated
* Customization options are available for all avatars
* Users have access to a history of their previously generated AI avatar customizations and can revert to any earlier version at any time.
* Customization options are automatically disabled (grayed out) when the user does not have sufficient balance (points, gems, or diamonds) to purchase them.

{% hint style="info" %}
**Note:** You can enable or disable avatar customization for the users via the Label settings, with the option to make it available to all users (test and real), only to test users, or to disable it completely.
{% endhint %}

#### Creating Customizations (Prompts)

You can create Customizations (Prompts) in the `BO -> Gamification -> Avatars -> Customize Avatars`.

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-1e811538bc04f909a7906cfef6ce62fb5b4ee158%2FScreenshot_49.png?alt=media" alt=""><figcaption><p>BO: Customize Avatars - Creating a Prompt</p></figcaption></figure>

Each customization (prompt) includes:

* **Name** (e.g., Red Hat) - Displayed on the avatar customization screen
* **Active** (Active / Inactive) - Inactive customizations are hidden from the UI
* **Prompt** (Description) - Explains what the customization does. Enter a clear action-based description (e.g., ‘add green glasses’ or ‘change hair to long’). Start with a verb and be specific for best results.
* **Prompt icon** - Shown next to the customization name in the UI (50×50 pixels). It is not a reference image for the AI.
* **Cost per player** (e.g., 5 Gems) - Displayed on the avatar customization screen, indicating the price the user must pay to apply the customization.

You can preview a customization with the **Test Prompt** button at the top of the customization form:

1. Select the avatar you want to test in **Choose Avatar**
2. Enter the customization in the **Prompt** field
3. Click **Run Test**

The system will generate a preview of the customization for the selected avatar. This is for demonstration purposes only and may differ from actual results.

<div><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-aa45d544ce7661666bdaeba6240888d8a6df24f9%2FScreenshot_50.png?alt=media" alt=""><figcaption><p>BO: Customize Avatars - Test prompt</p></figcaption></figure> <figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-3cdc5d28fbefd30758ffd9199327d57dd5a86881%2FScreenshot_51.png?alt=media" alt=""><figcaption><p>BO: Customize Avatars - Test prompt</p></figcaption></figure></div>

**Example:**

A user opens their avatar in the gamification widget and selects a customization option such as “Red Hat” from the available presets configured in the BO. This option was created by the operator and is available to all avatars.

The user sees that applying this customization costs 5 Gems, which they must pay to proceed. After confirming the payment, the system uses the predefined AI prompt to generate a new variation of the avatar with the selected feature applied.

Each time the user applies the same or a different customization (e.g., adding green glasses or changing hairstyle), a new unique version of the avatar is generated. These customization options are consistent across all avatars and are not specific to a single avatar type.

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-44270909bf7f4b1e8aa8b98b605d3c0a0ee388c0%2FScreenshot_4.png?alt=media" alt="" width="563"><figcaption><p>GF: Customizing an avatar</p></figcaption></figure>

#### Usage limits

Avatar customization is controlled by two types of limits: per-user limits and global (operator) limits. Usage limits are in place to help manage costs and prevent individual users from overusing the AI service. When any of the defined limits is reached, the player will see an error message in the UI. Both error messages can be customized in the Translations section.

1\. Player Monthly Limit Reached (per-user)

**Error message:**\
\&#xNAN;*You have exceeded the number of avatar customizations. Please try again later.*

**What this means:**

* The player has reached their personal monthly limit (50 customizations per month by default)
* No further customizations are allowed for this user until the next calendar month

2\. Operator Monthly Limit Reached (global limit)

**Error message:**\
\&#xNAN;*Avatar customization is currently unavailable. Please try again later.*

**What this means:**

* The operator has a total monthly limit for all users combined (100 customizations per month by default)
* This limit has been reached, so the feature is temporarily unavailable for all users
* This is not related to the individual player’s usage

### Legacy Avatars

We also support a legacy avatar mode where users are assigned a random avatar by default and can change it later. If this mode is not enabled, users will instead see an image representing the level they have achieved.

In this legacy setup, you can upload a set of custom avatar images in the BO. However, this mode has limited functionality: it does not support visibility rules, avatar assignments to missions, tournaments, mini-games, or store items, and avatar customization is not available.

### Frequently Asked Questions

**How do I give avatars to a player in a Campaign Journey or Automation Rule?**

Add an activity in your Journey campaign or Automation Rule, choose **Avatar(s)**, and select one or more avatars (up to 50) in the **Avatar(s)** field. Use **Select all** to add every avatar assigned to this context. All selected avatars are granted automatically when the player reaches that step.

**What happens if a player is awarded an avatar they already own?**

Avatar delivery is idempotent. If a player receives an avatar they have already unlocked or purchased, the system skips it without creating duplicate items or causing errors. When a reward gives several avatars, the player receives only the ones they don't own yet. Inactive avatars, deleted avatars and avatars outside their availability period are also skipped, and the rest of the set is still granted.

**Can I see reports on which avatars are most popular among players?**

Yes. Avatar unlocks and customizations are recorded in analytical reports and data warehouse exports. You can track player adoption and identify the most popular avatars through Custom Reports or by contacting your Success Manager.

**What image format and dimensions should I use for custom avatars and prompt icons?**

Avatar images should be square images sized 256×256 pixels (PNG, JPG or WebP). Customization prompt icons should be 50×50 pixels. You can also create icons and avatar art directly using the **Create** button of the image field (when AI image generation is enabled for your label) in the Back-Office.

<figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-27bed867fa4d2d7efac9556583e4256b2e580e65%2FScreenshot_52.png?alt=media" alt=""><figcaption><p>GF: Legacy Avatars</p></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.smartico.ai/welcome/products/gamification-basics/avatars.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
