Guides

Web Inbox

Suggest Edits

Web Inbox is a feature of Embedded Messaging that provides a persistent, in-app space for your users to view and manage messages. It is powered by the Optimove Web SDK, which handles both user tracking and the delivery of rich, targeted content directly within your web application.

Getting Started: The Optimove Web SDK

Integrating the Optimove Web SDK automatically enables the Web Inbox. For the vast majority of use cases, this is the only step required to get the inbox running.

Add the Web SDK Script

Add the following script to every page of your website, replacing the placeholders with your tenant-specific details. This single script loads and initializes the SDK, enabling all its features, including the Web Inbox.

<script async src="https://sdk.optimove.net/v2/websdk/?tenant_id=<YOUR_TENANT_ID>&tenant_token=<YOUR_TENANT_TOKEN>"></script>

Once the SDK is integrated and a user is identified on your site (e.g., by reporting a login event), the Web Inbox and its launcher badge will appear automatically according to your campaign settings.

Customizing the Appearance (Styling)

You can extensively customize the look and feel of the Web Inbox to match your brand's design. Styling is managed using CSS Custom Properties (variables) within a <style> tag on your page. The inbox is rendered in a Shadow DOM to prevent style conflicts with your main page.

How to Apply Styles

To override the default styles, define your desired CSS variables within a :root block in your site's CSS.

Example:

<style>
    :root {
        --optimove_inbox_header_background_color: #F10A69;
        --optimove_inbox_badge_background_color: #F10A69;
        --optimove_inbox_badge_border_radius: 50%;
        --optimove_inbox_font_family: 'Roboto', sans-serif;
    }
</style>

💡

Using Custom Fonts?

If you use a custom font, remember to import it in the <head> of your page before the style block, for example: <link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">.

Styling Reference

The tables below list the available variables for customizing the Web Inbox, grouped by component.

Main Inbox Component

These variables affect the overall appearance and layout of the main inbox window.

VariableDescriptionExample Value
--optimove_inbox_font_familyMain font used for all text in the inbox.Verdana, sans-serif
--optimove_inbox_z_indexSets the base z-index of the inbox. Layers 1-4 are set automatically above this.9999
--optimove_inbox_background_colorBackground color of the entire inbox.#FAFAFA
--optimove_inbox_widthWidth of the inbox component on non-mobile screens.380px
--optimove_inbox_heightHeight of the inbox component on non-mobile screens. Use vh for viewport height.80vh
--optimove_inbox_margin_topMargin from the top edge of the page.20px
--optimove_inbox_margin_bottomMargin from the bottom edge of the page.20px
--optimove_inbox_margin_horizontalMargin from the left or right edge of the page.20px
--optimove_inbox_vertical_alignVertical alignment when height is < 100%. start, center, or end.center
--optimove_inbox_paddingPadding for the main content area.16px

Header

Variables for the header section containing the "INBOX" title and close button.

VariableDescriptionExample Value
--optimove_inbox_header_background_colorBackground color of the header.blue
--optimove_inbox_header_font_weightFont weight of the header title.bold
--optimove_inbox_header_text_font_sizeFont size of the header title.24px
--optimove_inbox_header_text_colorColor of the header title.white
--optimove_inbox_header_bell_fillFill color of the bell icon in the header.white
--optimove_inbox_header_close_button_fillFill color of the close (X) icon.white

Messages

Variables for styling individual messages within the inbox list.

VariableDescriptionExample Value
--optimove_inbox_message_background_readBackground color for messages that have been read.#E0E0E0
--optimove_inbox_message_background_unreadBackground color for unread messages.#FFFFFF
--optimove_inbox_message_border_radiusAdds rounded corners to message cards.8px
--optimove_inbox_message_title_font_sizeFont size for the message title.16px
--optimove_inbox_message_title_font_colorColor for the message title.#333333
--optimove_inbox_message_font_sizeFont size for the message body text.14px
--optimove_inbox_message_font_colorColor for the message body text.#555555

Action Menu

Variables for the context menu (3-dots) on each message.

VariableDescriptionExample Value
--optimove_inbox_message_action_button_colorColor of the 3-dots icon and timestamp text.#007BFF
--optimove_inbox_action_menu_background_colorBackground color of the pop-up menu.#FFFFFF
--optimove_inbox_action_menu_colorColor of the icons and text inside the menu.#333333
--optimove_inbox_action_menu_hover_colorText and icon color on hover.#007BFF

Launcher Badge & Alert

Variables for the floating badge that opens the inbox and the unread count alert.

VariableDescriptionExample Value
--optimove_inbox_badge_rightPosition from the right edge of the screen.25px
--optimove_inbox_badge_bottomPosition from the bottom edge of the screen.25px
--optimove_inbox_badge_widthWidth of the badge.60px
--optimove_inbox_badge_heightHeight of the badge.60px
--optimove_inbox_badge_background_colorBackground color of the badge.#007BFF
--optimove_inbox_badge_border_radiusCorner roundness of the badge.50%
--optimove_inbox_badge_bell_colorColor of the default bell icon.white
--optimove_inbox_badge_alert_background_colorBackground color of the unread count circle.#DC3545
--optimove_inbox_badge_alert_font_colorFont color of the unread count.white

Advanced API Usage

For deeper integration, you can use the Web Inbox APIs directly. This provides direct access to fetch message data, manage message states, and build a fully custom user experience outside of the default component.

Using the SDK's API (Client-Side)

Once the Web SDK is initialized on your site, it provides a powerful client-side API to manage messages directly in the browser. This is ideal for Single Page Applications that need to refresh message data without a full page reload. Key capabilities include:

  • Fetching Messages: Retrieve all messages or filter for messages in specific containers.
  • Managing Message State: Programmatically mark messages as read or unread.
  • Reporting Engagement: Send metrics for clicks and other interactions to track campaign performance.

For detailed code examples, see the Using the SDK for Embedded Messaging guide.

Using the REST API (Server-Side / Custom UI)

For implementations that require a completely custom UI or need to manage messages from a backend service, you can interact with the Embedded Messaging V2 REST API directly. The easiest way to do this is by generating a type-safe client library from its OpenAPI specification.

This approach gives you full control over the user experience and allows for deeper integration with your own systems.

1. Generate the Client Library

Use the OpenAPI Generator to create a client library for your target language (e.g., TypeScript, Java, Swift).

config.json

{
  "useObjectParameters": true,
  "enumUnknownDefaultCase": true,
  "supportsES6": true,
  "npmName": "optimove-inbox-api",
  "npmVersion": "1.0"
}

 

{
  "groupId": "com.yourcompany",
  "artifactId": "optimove-inbox-api",
  "invokerPackage": "com.yourcompany.optimoveinbox",
  "version": "1.0",
  "failOnUnknownProperties": false,
  "enumUnknownDefaultCase": true
}

{
  "projectName": "OptimoveInboxApiClient",
  "podVersion": "1.0",
  "enumUnknownDefaultCase": true
}

Generator Command

java -jar openapi-generator-cli.jar generate \
    -g <TARGET_LANGUAGE> \
    -i <API_URL>/swagger/v1/swagger.json \
    -c config.json \
    -o <OUTPUT_DIRECTORY>

2. Use the API

Once the library is integrated into your project, you can use it to fetch messages and report events.

import * as inboxApi from "optimove-inbox-api";

const api = new inboxApi.MessageApi();

async function getUserMessages(customerId: string) {
  const messages = await api.getUserMessages({
    customerId: customerId,
    brandId: "your_brand_id",
    tenantId: your_tenant_id,
  });
  return messages;
}

 

import com.yourcompany.optimoveinbox.api.MessageApi;
import com.yourcompany.optimoveinbox.model.MessageResponse;
import java.util.List;

public class MessageHelper {
    private MessageApi api = new MessageApi();
    
    public List<MessageResponse> getMessages(String customerId) {
        try {
            return api.getUserMessages(
                customerId,
                null,
                null,
                your_tenant_id,
                UUID.fromString("your_brand_id")
            );
        } catch (ApiException e) {
            e.printStackTrace();
            return new ArrayList<>();
        }
    }
}

import OptimoveInboxApiClient

func getUserMessages(customerId: String) async -> [MessageResponse] {
    await withCheckedContinuation { continuation in
        OptimoveInboxApiClient.MessageAPI.getUserMessages(
            customerId: customerId,
            tenantId: your_tenant_id,
            brandId: UUID(uuidString: "your_brand_id"),
            completion: { (messages, error) in
                continuation.resume(returning: messages ?? [])
            }
        )
    }
}

Updated 17 days ago