> 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.

### 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 (this ensures legacy avatars remain visible for real users while testing) * Set avatar customization to be visible only 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. {% endhint %} #### Creating an Avatar To create an avatar, go to the **Avatars** section in the BO and click the **Create** button.

BO: Avatars template - Additional section

When creating an avatar, you can: * **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, SVG, or WebP format. You can also generate avatar images directly in the Back-Office using the built-in AI Image button in the upload field. * **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 * Free → users can use it immediately * Reward-based → users must earn or purchase it {% hint style="info" %} **Note:** If the avatar is assigned to a Store item, it is recommended to limit the item to a one-time lifetime purchase. Otherwise, players may be able to purchase the same avatar multiple times, which can lead to a poor user experience. 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 \[\[products/gamification-basics/marketplace]]. {% 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) * Show as Locked - the avatar is visible to players but displayed as unavailable (grayed out) * Hide until earned - the avatar remains hidden until it is unlocked through a mission, tournament, mini-game, etc.. * **Set priority** - Display order. Controls how avatars are ordered in the widget **Using Avatars as Rewards** - Avatars can be given to users through: * Mission * Badge * Tournament * Mini-game * Store item * Raffle * Campaign reward * Automation Rule reward ### 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`.

BO: Customize Avatars - Creating a Prompt

Each customization (prompt) includes: * **Name** (e.g., Red Hat) - Displayed on the avatar customization screen * **Status (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. * **Icon** - Shown next to the customization name in the UI * **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 using the Test Prompt feature: 1. Select the avatar you want to test 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.

**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.

#### 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 (e.g., 100 customizations per month) * No further customizations are allowed for this user until the limit resets 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 (e.g., 1000 customizations per month) * 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 an avatar to a player in a Campaign Journey or Automation Rule?** Add an action node in your Journey campaign or Automation Rule, choose the **Avatar** action type, and select the desired avatar from the list. The avatar will be granted automatically when the player triggers 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 safely records the grant without creating duplicate items or causing errors. **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, SVG, or WebP). Customization prompt icons should be 50×50 pixels. You can also create icons and avatar art directly using the AI generation button inside the Back-Office.

--- # 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=&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.