Guides

Web Inbox

Suggest Edits

The Web Inbox is a feature of embedded messaging that provides a persistent, in-app space for users to view and manage messages. This guide covers how to initialize the inbox on your website, customize its appearance, and interact with its API using a generated client library.

Initialization

Getting the Web Inbox running on your site is straightforward. You'll need to add a script tag to your HTML and then call the initialization function with your specific configuration details.

  1. Add the Script: Place the following script tag in the <head> of your HTML file.
  2. Initialize the Inbox: Add a second script block to call the Optimove.Inbox.init function, providing your tenantId, brandId, and the customerId of the logged-in user.
<head>
    <script src="[https://path.to/optimove/inbox.js](https://path.to/optimove/inbox.js)" async></script>

    <script type="text/javascript">
        Optimove.Inbox.init({
            tenantId: YOUR_TENANT_ID,      // Replace with your Tenant ID
            brandId: 'YOUR_BRAND_ID',       // Replace with your Brand ID
            customerId: 'CUSTOMER_ID'       // Dynamically insert the current user's ID
        });
    </script>
</head>

Once initialized, the Web Inbox and its launcher badge will appear on your page according to your campaign settings.

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

Client Library Features

For programmatic interaction with the Web Inbox API (e.g., fetching or deleting messages from your own application backend), you can generate a client library. This allows you to easily integrate inbox functionalities into your native mobile apps or other services.

Generating a Client Library

The library is created using the OpenAPI Generator.

Prerequisites

  • Install the OpenAPI Generator CLI. The following examples assume a local JAR file installation.
  • Know your region-specific Inbox API URL.

Usage Steps

  1. Create a config.json file to specify options for the generator. Ensure you set enumUnknownDefaultCase to true for future compatibility.
// config.json
{
  "enumUnknownDefaultCase": true
  // Add other language-specific options here
}
  1. Run the generator command, replacing the placeholders with your target language, API URL, and desired output directory.
java -jar openapi-generator-cli.jar generate \
    -g <TARGET_LANGUAGE> \
    -i <API_URL>/swagger/v1/swagger.json \
    -c config.json \
    -o <OUTPUT_DIRECTORY>

Worked Examples (TypeScript, Java, Swift)

Here are the specific steps and configurations for common platforms.

1. Configure and Generate

Create a config.json file for your target language and then run the corresponding generate command.

{
  "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

# For TypeScript
java -jar openapi-generator-cli.jar generate -g typescript ...

# For Java
java -jar openapi-generator-cli.jar generate -g java ...

# For Swift
java -jar openapi-generator-cli.jar generate -g swift5 ...

2. Add the Library to Your Project

The generated library includes a README.md with detailed instructions. Common methods include:

  • TypeScript: Publish as a private NPM package and npm install it, or install it as a local package.
  • Java (Android): Install it to your local Maven repository (mvn clean install) and add it as a dependency in your pom.xml or build.gradle file.
  • Swift (iOS): In Xcode, use File > Add Package Dependencies... and add the generated library as a local package.

3. Use the API

Once integrated, you can use the library to fetch a user's inbox messages.

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 about 4 hours ago