> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatmode.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed Customization

Customize your Chatmode embed to match your brand and provide a seamless user experience. Customization involves configuring options in the Chatmode UI, potentially passing parameters during initialization, and applying custom CSS.

## Configuring via Environment Settings (Chatmode UI)

Most visual and behavioral aspects of the chat interface *inside* the modal/iframe are configured within the Chatmode application when you set up your `EMBED` type Environment.

Navigate to **Environments -> \[Your Embed Environment] -> Settings** in Chatmode to configure:

* **Display Name**: The text shown in the chat header.
* **Display Picture**: The logo or avatar shown in the chat header.
* **Icon**: The icon displayed on the floating chat bubble when closed.
* **Primary Color**: Affects buttons and other accents within the chat interface.
* **Initial Message**: The first message the Agent sends when the chat loads.

Changes made here automatically reflect in the embed.

## Configuring via `initBubble` Options

The `Chatmode.initBubble` function, used in the standard Bubble Code snippet copied from the Chatmode UI, accepts a few client-side options to control the theme and custom icon:

```html theme={"system"}
<script type="module">
  import Chatmode from "https://cdn.jsdelivr.net/npm/@chatmode/embed/+esm";

  Chatmode.initBubble({
    // Required - Copied from UI
    environmentId: "YOUR_ENVIRONMENT_ID",

    // Optional Configuration
    theme: "automatic", // "light", "dark", or "automatic" (default)

    // Optional - Pre-filled if icon uploaded in UI - Copied from UI
    // iconKey: "YOUR_ICON_KEY",
    // updatedAt: TIMESTAMP, // Cache-buster for icon
    position: "bottom-right", // "bottom-left" or "bottom-right" (default)
  });
</script>
```

* **`environmentId` (Required)**: Your specific Environment ID, obtained from the snippet copied in the Chatmode UI.
* **`theme` (Optional)**: Controls the color scheme (`light`, `dark`, or `automatic` based on user's system preference). Defaults to `automatic`.
* **`iconKey` (Optional)**: The identifier for your custom icon uploaded in the Environment settings. This is usually pre-filled in the copied snippet if you uploaded an icon.
* **`updatedAt` (Optional)**: A timestamp used to prevent incorrect browser caching of the icon image. This is usually pre-filled along with `iconKey`.

**Important:** All other customizations, such as the chat header's Display Name, Display Picture, the agent's Initial Message, and the bubble's main Icon and Primary Color, are configured **exclusively** within the Environment settings in the Chatmode UI.

*Note: Always start with the code snippet copied from the Chatmode UI, as it contains the required `environmentId` and potentially pre-filled `iconKey` and `updatedAt`.*

## Programmatic Control

When you initialize the bubble, you can optionally store the returned control object:

```javascript theme={"system"}
const chat = Chatmode.initBubble({
  environmentId: "YOUR_ENVIRONMENT_ID",
  theme: "automatic",
  iconKey: "YOUR_ICON_KEY",
  updatedAt: TIMESTAMP,
  position: "bottom-right",
});

// Now you can use the 'chat' object:

// Open the chat modal
chat.open();

// Close the chat modal
chat.close();

// Toggle the modal
chat.toggle();

// Check if the modal is open
if (chat.isOpen()) {
  console.log("Chat is open");
}

// Remove the bubble and modal completely
// chat.remove();
```

This allows you to trigger chat actions from your own website's code, for example, opening the chat when a user clicks a custom "Help" button.

## Styling with CSS

CSS is primarily used if you opt for the **Inline Embed** method (using an `<iframe>` tag directly) rather than the standard floating bubble.

### Styling the Inline Iframe Container

If you use the `<iframe>` code snippet (copied from the Environment settings as an alternative to the Bubble Code), apply standard CSS to the `<iframe>` tag itself to control its `width`, `height`, `border`, `margin`, `position`, etc., to integrate it seamlessly into your page layout.

```css theme={"system"}
/* Example for an iframe with ID 'chatmode-inline-iframe' */
#chatmode-inline-iframe {
  width: 100%;
  max-width: 500px; /* Example constraint */
  height: 600px;
  border: 1px solid #eee;
  border-radius: 8px;
  margin: 20px 0;
}
```

### Styling the Floating Bubble (Not Recommended)

While technically possible using browser developer tools to find CSS selectors and overriding them with `!important`, manually overriding the styles of the floating bubble (`#chatmode-bubble-button`) or its modal window (`.chatmode-modal-container`, etc.) is **not recommended or supported**. These internal structures may change without notice, breaking your custom styles.

Stick to the customization options provided in the Environment settings (Display Name, Picture, Icon, Color, Initial Message) and the `theme` option in the `initBubble` script for the standard floating bubble.