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

# Advanced Usage

> Advanced SDK features for widget control, event handling, and custom integrations

This page covers advanced usage of the Remark SDK, providing developers with more sophisticated control over the chat widget and user experience.

<CardGroup cols={2}>
  <Card title="Initialization" icon="clock" href="#waiting-for-remark-to-initialize">
    Safely wait for the SDK before calling window\.remark.
  </Card>

  <Card title="Widget Control" icon="sliders-horizontal" href="#customizing-your-user-experience-with-the-remark-sdk">
    Programmatically open, close, hide, and show the chat widget.
  </Card>

  <Card title="Event Handling" icon="code" href="#listening-for-remark-events">
    Listen to user interactions and create custom integrations.
  </Card>
</CardGroup>

## Waiting for Remark to initialize

Because the Remark script loads asynchronously, `window.remark` may not be available when your code runs. Before calling `window.remark`, wait for the `remark:session-initialized` event on `window`:

```javascript theme={null}
window.addEventListener('remark:session-initialized', () => {
  // window.remark is now ready
  window.remark('open');
});
```

If your code might run before or after initialization, you can check whether `window.remark` is already available:

```javascript theme={null}
function whenRemarkReady(callback) {
  if (typeof window.remark === 'function') {
    callback();
  } else {
    window.addEventListener('remark:session-initialized', callback, { once: true });
  }
}

// Usage
whenRemarkReady(() => {
  window.remark('open', { from: 'promo-banner' });
});
```

## Customizing your user experience with the Remark SDK

The Remark SDK can also be used to control the state of the chat widget.

You may wish, for example, to temporarily close the chat widget when displaying full-screen promotions *or* open the chat widget when a customer clicks on a certain call-to-action on your site.

You can **open**, **close**, **hide**, and **show** the chat widget using one of the options in the following code.

```javascript theme={null}
// To open the chat widget:
window.remark('open');
document.querySelector('remark-chat-widget').setAttribute('open', '');

// To close the chat widget:
window.remark('close');
document.querySelector('remark-chat-widget').removeAttribute('open');

// To entirely hide the chat widget:
window.remark('hide');
document.querySelector('remark-chat-widget').setAttribute('hidden', '');

// To show the chat widget again:
window.remark('show');
document.querySelector('remark-chat-widget').removeAttribute('hidden', '');
```

## Opening the widget with options

In addition to simply opening the widget, you can pass options to control its initial state and behavior.\
This is helpful when you want to start the chat from a specific context, prefill a message, or automatically send a greeting.

```javascript theme={null}
// Open the widget with additional context
window.remark('open', {
  from: 'category-page',
  message: 'Hi there! Can you help me find the right item?',
  mode: 'send'
});
```

### Available options

* **from** – A string identifier for where or why the widget was opened (for example, `homepage`, `checkout`, or `category-page`). Useful for analytics, tracking, or routing the conversation.
* **message** – A string to prefill in the chat input. When paired with `mode: 'send'`, this message will be sent automatically.
* **mode** – Controls message handling. Use `'send'` to send immediately or omit to just prefill the input.

This approach lets you personalize the chat experience and give your team useful context on how the conversation began.

<Info>
  **Embedded and floating widget coordination:** When both the floating chat (`<remark-chat-widget>`) and embedded chat (`<remark-qa-activator>`) appear on the same page, they coordinate automatically. Only one widget holds the active conversation at a time — the other shows a "paused" state with the matched expert's avatar and a button to resume the conversation there.

  On mobile viewports (480 px and below), tapping a prompt in the embedded chat opens the floating widget full-screen instead of starting an inline conversation. The floating widget does not auto-reopen from persisted state across page navigations on mobile — it stays closed unless explicitly opened via `remark_open=true` or `window.remark('open')`.
</Info>

## URL Parameters

Remark recognizes several URL parameters for controlling widget behavior without writing code. These are useful for testing and sharing links that demonstrate a specific widget configuration.

| Parameter                             | Effect                                                                                  |
| ------------------------------------- | --------------------------------------------------------------------------------------- |
| `remark_open=true`                    | Opens the floating chat widget on page load                                             |
| `remark_force_widget=true`            | Bypasses A/B test assignment — forces the widget to display regardless of control group |
| `remark_preview_inline_elements=true` | Shows the embedded chat even when it is disabled in the dashboard                       |

Append them as query parameters to any page URL:

```
https://www.example.com/products/hiking-boots?remark_force_widget=true
```

`remark_force_widget` and `remark_preview_inline_elements` are also written to `sessionStorage` when set via URL, so the override persists across page navigations within the same tab. You can also set them directly in `sessionStorage` — useful in browsers or environments that strip query parameters:

```javascript theme={null}
sessionStorage.setItem('remark_force_widget', 'true');
sessionStorage.setItem('remark_preview_inline_elements', 'true');
```

To clear an override, close the tab or remove the key from `sessionStorage` in DevTools.

## Listening for Remark Events

The remark-chat-widget element fires a number of "remark" namespaced events. To listen to any of them, place an event listener on the remark-chat-widget element, or anywhere higher on the DOM.

On the element directly

```javascript theme={null}
const widget = document.querySelector("remark-chat-widget");
widget.addEventListener("remark:mute-chat", () => {
  console.log("The user has toggled mute for the chat");
});
```

On the window

```javascript theme={null}
window.addEventListener("remark:mute-chat", () => {
  console.log("The user has toggled mute for the chat");
});
```

### Listen to all Remark Events

To listen to *all* the events, you can use the `window.remark.events.listenAll` function.  It takes a callback, called with every remark event.  The payload received by the callback is an object:

* with an `event__type` key, one of the [remark events listed below](#list-of-remark-events)
* any other details payload the event has with it

`listenAll` returns an object with an unsubscribe function.  Calling that unsubscribe function will stop the callback from being called again.

```typescript theme={null}
// typescript function declaration of listenAll
declare function listenAll(cb: (payload: {event__type: string} & {[key: string]: any}) => void) => {unsubscribe(): void};

// example calling listenAll
const listener = window.remark.events.listenAll(
  ({event__type, ...detail}) => {
    console.log(`The event fired is ${event__type} with this information ${detail}`)
  }
);

// unsubscribing the listener
listener.unsubscribe();
```

### List of Remark Events

| Event                                     | Description                                                               |
| ----------------------------------------- | ------------------------------------------------------------------------- |
| `remark:session-initialized`              | Our client session has initialized, with basic information for the widget |
| `remark:open-widget`                      | Remark chat widget has opened                                             |
| `remark:close-chat-from-header`           | Customer has closed the chat window via the chat header button            |
| `remark:mute-chat`                        | Fires when chat mutes or unmutes                                          |
| `remark:dismiss-floating-prompts`         | Customer has closed the floating prompts on the activator                 |
| `remark:dismiss-unread-message`           | Customer has dismissed the unread message on the activator                |
| `remark:finding-expert`                   | Customer is waiting to be paired with an expert                           |
| `remark:send-message`                     | Customer has sent a message                                               |
| `remark:select-landing-prompt`            | Customer has selected a suggested question on the floating landing screen |
| `remark:select-floating-activator-prompt` | Customer has selected a suggested question from the floating activator    |
| `remark:select-embedded-prompt`           | Customer has selected a suggested question from the embedded widget       |
| `remark:select-conversation-starter`      | Customer has selected a conversation starter in chat                      |
| `remark:click-recommended-product`        | Customer has clicked a recommended product                                |
| `remark:add-recommended-product-to-cart`  | Customer has added a recommended product to cart                          |
| `remark:click-showcase-product`           | Customer has clicked a product link in a presented showcase hover card    |
| `remark:add-showcase-product-to-cart`     | Customer has added a product from a presented showcase to cart            |
| `remark:agent-add-item-to-cart`           | Agent has added item(s) to cart                                           |
| `remark:adjust-cart-item-quantity`        | Customer has adjusted cart item quantity in the cart dialog               |
| `remark:click-checkout-button`            | Customer has clicked checkout from the cart dialog                        |
| `remark:apply-discount`                   | Customer has applied a discount code from a discount card                 |
| `remark:change-widget-size`               | Customer has changed the widget size                                      |
| `remark:change-widget-position`           | Customer has changed the widget position                                  |
| `remark:change-activator-type`            | Customer has changed the activator type                                   |
| `remark:view-expert-profile`              | Customer is viewing the expert profile                                    |
| `remark:close-expert-profile`             | Customer has closed the expert profile                                    |
| `remark:view-expert-gallery`              | Customer is viewing the expert's gallery                                  |
| `remark:submit-pii`                       | Customer has submitted requested PII                                      |
| `remark:decline-pii-request`              | Customer has declined a requested PII form                                |
| `remark:open-nps`                         | Customer has opened the NPS survey                                        |
| `remark:submit-nps`                       | Customer has submitted a Customer Feedback Survey                         |
| `remark:edit-nps`                         | Customer has edited a Customer Feedback Survey                            |
| `remark:cancel-nps`                       | Customer has canceled editing a Customer Feedback Survey                  |
| `remark:sdk-initialized`                  | Deprecated; use `remark:session-initialized` instead                      |