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

Widget Control

Programmatically open, close, hide, and show the chat widget.

Event Handling

Listen to user interactions and create custom integrations.

​
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 the following code. 
// To open the chat widget:
window.remark('open');

// To close the chat widget:
window.remark('close');

// To entirely hide the chat widget:
window.remark('hide');

// To show the chat widget again:
window.remark('show');

​
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. 
// 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.

​
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 
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 
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: listenAll returns an object with an unsubscribe function. Calling that unsubscribe function will stop the callback from being called again. 
// 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

EventDescription
remark:open-widgetRemark chat widget has opened
remark:mute-chatFires when chat mutes or unmutes
remark:finding-expertCustomer is waiting to be paired with an expert
remark:close-activator-explainerCustomer has closed the explainer card on our floating activator
remark:send-messageCustomer has sent a message
remark:close-chat-from-headerCustomer has closed the chat window via the chat header button
remark:view-expert-profileCustomer is viewing the expert profile
remark:close-expert-profileCustomer has closed the expert profile
remark:view-expert-galleryCustomer is viewing the expert’s gallery
remark:click-expert-socialCustomer has clicked on an expert’s social link
remark:support-link-buttonCustomer has clicked the support button
remark:continue-after-additional-promptingCustomer opted to initiate a chat after Remark suggested alternative customer support resources
remark:send-emailWhen the customer has submitted their email
remark:send-expert-intro-messageRemark widget is sending the customer’s first message to an expert
remark:skip-nameCustomer has chosen to skip inputting their name
remark:submit-nameCustomer has chosen to input their name
remark:click-chat-with-expertCustomer has entered the introduction flow
remark:additional-prompt-requiredThe customer’s initial inquiry appears to be related to post-purchase / warranty / replacement parts / etc. Remark will suggest visiting your brand’s support page. Alternatively, customer is given the option to proceed to chat
remark:support-linkCustomer clicked the support link
remark:skip-nps-from-activatorSkipping a Customer Feedback Survey because customer has asked a new question from the activator
remark:edit-npsCustomer has edited a Customer Feedback Survey
remark:skip-npsCustomer has chosen to skip Customer Feedback Survey
remark:cancel-npsCustomer has canceled editing a Customer Feedback Survey
remark:submit-npsCustomer has submitted a Customer Feedback Survey