> 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/crm-automation/communication-channels/inbox.md). # Inbox ## Overview Inbox is a separate communication channel similar in functionality to Facebook notifications. From the end-user perspective, it allows users to view and manage all their notifications in one place. It acts as a centralized hub for all notifications, making it easier for users to stay informed about the latest updates and interactions on your platform.

{% hint style="info" %} "Inbox communication channel" is enabled for any setup with CRM Automation. This is including the possibility to send "simple" inbox messages, and the end-user is able to see them as part of the Gamification widget. "Inbox widget" is an additional feature that needs to be enabled on your setup. It provides additional possibilities to: * Send notifications with rich content with the support of HTML * Displaying notifications in a separate widget independent from the Gamification widget * Possibility to get real-time updates about the count of unread messages per user All setups are limited to 1 million notification messages per month by default. Please contact your Success Manager for more details. {% endhint %} The Inbox can be accessed from the main Gamification widget or by clicking on the bell/envelope icon that you can place on the front end of your platform. Once you click on the bell icon, the Inbox widget will appear, displaying all the latest notifications.

BO: Example of inbox notifications. An older look: the field Message expiration period is now called **Active till**

Users can interact with notifications by adding them to their favorites, expanding a notification if it has additional details, or marking all notifications as read. ## Inbox template From the operator's perspective, every notification can have the following attributes * Title - a short subject for the notification * Body - a short presentation of the notification * Rich body - is an extended presentation of the notification with support of the HTML formatting * Icon - for the visual representation of the inbox notification * Deep link or URL - to direct the user when he is clicking on the inbox * Open links - choose whether links within the message open **In a new tab** (default) or **In the current tab** * Enable "zoom" mode for images - zoom in on images by clicking on them within the message (only for an **Inbox message with rich body**)

Rich body Inbox setup: 1 — Inbox message type; 2 — Rich body (HTML), edited in Vibe Studio; 3 — the deep link and text of the primary button; 4 — Open links; 5 — the rich preview

There are 2 types of notification messages that behave in different ways: * Simple inbox - has only a title, a short description, and an icon. Clicking such a message will navigate the user to a specified deep link or URL. * Inbox message with a rich body - has an additional rich body. Clicking such a message opens the Inbox widget with the notification in focus and expanded. Operators can configure dedicated Primary and Secondary CTA buttons with deep links in the Back-Office template, or include custom links directly inside the rich HTML body. ### Designing rich body messages with Vibe Studio When configuring an **Inbox message with rich body**, operators can design and refine the HTML content directly in **Vibe Studio** instead of writing raw markup: * **Opening Vibe Studio**: In the template editor, open the **Rich body (HTML)** field and click **Edit in Vibe Studio** (available once the template is initially saved). * **AI-Assisted Design**: Use the AI prompt assistant in Vibe Studio to generate layouts, format promotional text, create custom banners and illustrations, and insert dynamic player personalization tags. * **Interactive Live Preview**: Preview the message in real time within the actual Inbox widget layout, including title, preview text, and CTA buttons. Operators can also switch between different brand visual themes in the preview toolbar to verify how the notification appears across different widget skins. * **Applying Changes**: Once satisfied with the design, click **Apply & Save**. The HTML goes back into the **Rich body (HTML)** field of the template, and the template is saved. To edit the HTML by hand instead, open the arrow next to **Edit in Vibe Studio** and choose **Edit in legacy editor**. There is a set of additional configurations for the Inbox notifications: * For how long the inbox message will stay on the screen when sent to the user, the default value is 7 seconds, and can be adjusted for each inbox template * For how long the inbox message will stay in the notification center of the user (the **Active till** field), the default value is 60 days, and it can be adjusted for each inbox template. You can choose between a **Relative period** or an **Exact period** (a date when the message will disappear). The date can be at most 365 days ahead. * For the "Inbox widget", you can define how it can be closed - either by clicking on the "X" icon inside the inbox widget or, additionally, by clicking outside of the widget * You can configure it to show a preview of the message for a short period when the user is online, and define the position of that message for mobile and desktop devices, either in label settings or individually per template. * Message categories - assign messages to categories (**General**, **System**, or **Personal**) to enable category tabs and filtering in the Inbox widget. The field can be changed only when **Show message categories in inbox** is turned on in the widget settings of the label. * Short preview character recommendation - keep short body preview text around 80 characters for optimal toast rendering on mobile and desktop without truncation. * Search keywords - add tags to organize and quickly search for inbox templates in the Back-Office. ## Inbox message lifecycle There are the following lifecycle stages of the inbox message * The message is created as part of the Journey or Scheduled campaign * If the user is online, it will be delivered to him; otherwise, it will stay in the delivery pool for the period specified by the operator (20 seconds by default) * When a message is delivered to the end user while he is online, it appears as a short preview in the bottom-right or upper-right corner of the screen, as set in the template or in the label settings. The preview shows only when **Show preview of the message for a short period if user is online** is on in the template (it is on by default). At this moment, the message's "impression" will be recorded. * If the message is defined as "Simple," clicking it will take the user to the Deep Link or URL specified in the template. * If the message has a rich body, clicking it opens the Inbox widget with the message in focus. * The "read" status of the message will be set when the user clicks the message, regardless of whether the message has a rich body. * Delivery timeout vs message persistence - the **Delivery timeout** of the Inbox activity (20 seconds by default) is how long Smartico waits to deliver the message to the player. If the message isn't delivered in that time, the activity fails with **Execution timeout** and the flow continues down the **Failed** branch. By default, the message is still kept in the player's inbox until its **Active till** date or until it is recalled, so the player can open it later and an impression is recorded then. To remove the message when the timeout is reached, enable the "Expire the inbox on timeout" option. {% hint style="info" %} **Caps impact** You can configure user-level and global-level caps for Inbox messages. If [communication caps](https://help.smartico.ai/welcome/products/crm-automation/communication-channels/communication-caps) are configured and exceeded, the inbox activity will fail (Cannibalisation) and the message will not be delivered to the end user or saved in their inbox history. The **Caps status impact** option of the Inbox activity in the flow can make the activity ignore the user-level caps, the global caps, or both (by default it respects both). {% endhint %} #### **Recall Inbox messages** Initiating a recall removes the message from all recipients' inboxes in the background. While the process starts immediately, completing the deletion across all users may take some time depending on audience size.

BO: Example of recalling an inbox message

## Sending inbox messages through the API You can send messages to end users via the Smartico REST API. General documentation about Smartico REST API can be found in the Back Office in the Label \ Using Rest API section. To make a call to the API, you need to specify a private authorization key, which you can request from your Success Manager. ```bash curl --request POST \ --url 'https://apis.smartico.ai/api/external/events/v2' \ --header 'Authorization: your-private-auth-key' \ --header 'Content-Type: application/json' ``` {% hint style="info" %} Note: depending on your setup and geographical location, the URL of the API can be different {% endhint %} Example of the JSON body to deliver an inbox message ```json [ { // unique UUID of the request "eid": "96b60b08-25f0-4129-b363-ef0d4db780ef", // UTC timestamp of the request "event_date": 1680106470149, // brand_id as it is identified in your system. // if you don't know, please consult with your Success Manager "ext_brand_id": "your-external-brand-id", "user_ext_id": "id-of-the-user-your-system", "event_type": "core_personal_message", "payload": { "title": "Title of the inbox message", "short_message": "Short message", "rich_message": "some rich message", "icon": "https://mycnd.com/image.png", "channel": "inbox-api" } } ] ``` Before sending the message, you need to create Journey and Inbox templates in the Smartico BackOffice. You should create an inbox message template as defined in the screenshot below. Pay attention to the tag names; they should match the field names sent in the API request. You can also add your own styles and HTML in the rich message that will be used for all the messages you are going to send.

Inbox template for API messages: 1 — Title takes {{event.title}}; 2 — Body takes {{event.short_message}}; 3 — Rich body (HTML) holds {{event.rich_message}}

The journey should be triggered by "Core: send personal message" trigger and the "inbox-api" should be set for the "Core: personal message channel", as specified in the screenshot below.

Setting the trigger for the Journey: 1 — Core: send personal message; 2 — the channel condition, inbox-api

You should set the entry mode to "Every time conditions are met.." and campaign duration to 1 minute.

Create a Journey flow as shown on the screen below. Use the Inbox template created before.

### Sending personal inbox messages from Back Office Operators can also send an ad-hoc Inbox message directly to an individual player from their profile in the Back-Office without setting up a scheduled campaign. For more details, see [Sending personal messages from Back Office](/welcome/products/crm-automation/communication-channels/sending-personal-messages-from-back-office.md). ## Technical integration For the technical details related to the integration of the Inbox widget, please refer to the [Extended integration](/welcome/technical-guides/front-end-integration/extended-integration/player-profile-and-gamification-ui.md#inbox-widget) article. ## Revamped Inbox We've entirely redesigned our Inbox feature. This update offers a more intuitive and enjoyable experience when navigating messages, staying updated with notifications, and effortlessly managing your communications.

Gamification: Example of message with rich body

**New Improvements:** * **CTA Buttons** - we've introduced two new call-to-action (CTA) buttons for messages with rich content, which are also visible within the notifications. They can be configured through the BO, allowing operators to include deep links in both primary and secondary message buttons. * **All tab** and **Favorite tab** - offer distinct and clear separation between all your messages and those designated as favorites. * **Show unread toggle** - with the new switch, you can effortlessly view all unread messages in both the All and Favorites tabs. * **Enhanced expand mode for messages** - Regardless of rich content, all messages can now be expanded for improved readability and clarity.

Gamification: Example of simple inbox message

* **Back-to-top button** - Our latest update includes a back-to-top button for seamless navigation back to the top of the page with a single click after scrolling down. * **Load more button** - for a better user experience we have added the Load more button. After the 20th message, click the 'Load More' button to reveal additional messages. * **Empty inbox animation** - we have added an animation for the cases where you don’t have any messages in the inbox. * **The stand-alone mode** was also revamped

Gamification: Example of standalone inbox

## Add sound for incoming inbox messages You can enable a sound alert when players receive an inbox message. The setting, **'Enable sound for receiving inbox,'** is located in the inbox template within the BO. By default, this option is turned off, meaning no sound will play when a message arrives. When enabled, players will hear a default notification sound, and you can also upload a custom sound of your choice. ## FAQ ### Is an Inbox message guaranteed to arrive if the player is offline? By default, yes. When an Inbox activity is triggered, the message is stored in the player's inbox history immediately. If it isn't delivered within the **Delivery timeout** (default 20 seconds), the activity fails with **Execution timeout**, but the message remains accessible in the player's Inbox widget until its **Active till** date. If **Expire the inbox on timeout** is enabled in the Inbox activity, the message is removed from the inbox when the Delivery timeout is reached, and the player won't see it later. ### Why did an Inbox message fail to deliver to a player? An inbox message can fail for the following reasons: * **Inactive account status**: The player's account status is blocked, suspended, or excluded for the campaign category. * **Communication caps**: If daily or hourly user-level or global caps are exceeded, the send fails due to cannibalisation (unless the **Caps status impact** option of the Inbox activity ignores those caps). * **Tag replacement failure**: A dynamic tag or personalization placeholder could not be resolved. * **Message expiration**: The message's relative or exact expiration date passed before the player opened their inbox. ### How can I remove an Inbox message after a player completes a deposit or accepts an offer? * **Recall message**: Use the **Recall Message** button in the Back-Office template to remove the message from all players' inboxes. * **Set a short expiration**: Configure the template's **Active till** duration to auto-expire the message after a short period. * **Front-end SDK**: Use the front-end SDK inbox deletion method to remove the notification for a specific player. ### How do I personalize Inbox messages with dynamic mission or reward details? You can use Smartico dynamic tags and Liquid syntax in the Title, Body, and Rich Body HTML. When a campaign is triggered by a player action (such as completing a mission or receiving a bonus), you can insert event data tags or user profile tags directly into the message content. ### Where are the Inbox toast button and notification colors configured? Visual styles, including call-to-action button colors and widget themes, are configured globally in **Label Settings / Brand Settings > Widget Settings (Theme Editor)**. The individual Inbox template controls button text, deep link destinations, and icons, while the global theme determines branding colors.

--- # 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/crm-automation/communication-channels/inbox.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.