Control Notiondesk Messenger with the JavaScript SDK

The Notiondesk Messenger JavaScript SDK lets you integrate Messenger directly with your application's interface and state.

You can:

• Open and close Messenger from your own UI

• Send visitors directly to Help, Messages, Contact, or Changelog

• Build your own Messenger launcher

• React to Messenger events

• Synchronize Messenger with your application's theme and language

• Update authenticated users without reloading the page

• Change position and stacking at runtime

• Integrate Messenger with React and Vue application state

• Remove and reinitialize Messenger when needed

Use the SDK for applications that need more control than the standard Messenger installation snippet provides.

Install the SDK

Install the official package:

npm install @notiondesk-so/messenger-js-sdk

You can also use Yarn:

yarn add @notiondesk-so/messenger-js-sdk

Or pnpm:

pnpm add @notiondesk-so/messenger-js-sdk

Initialize Messenger

Import initNotiondesk() and provide your Messenger ID:

import { initNotiondesk } from "@notiondesk-so/messenger-js-sdk";

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

initNotiondesk() resolves when Messenger is ready to use, so the safest pattern is to wait for initialization before calling SDK methods:

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

await notiondesk.show();

Notiondesk Messenger must be initialized in the browser. Do not initialize it during server-side rendering.

For React and Next.js installation, see How to install Notiondesk Messenger with React and Next.js.

Open, close, and toggle Messenger

Open Messenger

Use show():

await notiondesk.show();

For example:

document.querySelector("#support")?.addEventListener("click", () => {
  void notiondesk.show();
});

Close Messenger

Use hide():

await notiondesk.hide();

Toggle Messenger

Use toggle() to open Messenger when it is closed and close it when it is open:

await notiondesk.toggle();

toggle() is particularly useful when your application provides its own Messenger button.

Open a specific Messenger section

Use showTab() to open Messenger directly on a specific module:

notiondesk.showTab("help");

Available tabs are:

For example:

helpButton.addEventListener("click", () => {
  notiondesk.showTab("help");
});

updatesButton.addEventListener("click", () => {
  notiondesk.showTab("changelog");
});

contactButton.addEventListener("click", () => {
  notiondesk.showTab("contact");
});

showTab() also opens Messenger if it is currently closed.

The requested module must be enabled in your Messenger configuration. For example, showTab("changelog") will not switch to Changelog if the Changelog module is disabled.

This makes it possible to connect different parts of your application's interface to different support experiences.

For example:

• Help Center → showTab("help")

• Ask AI → showTab("messages")

• Contact support → showTab("contact")

• What's new → showTab("changelog")

Use your own Messenger button

You do not have to use the default Notiondesk launcher.

Turn off Show launcher in your Messenger settings, then use the SDK to open Messenger from your own interface.

For example:

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

document.querySelector("#help")?.addEventListener("click", () => {
  void notiondesk.toggle();
});

This is useful when support should be integrated into an existing navigation bar, account menu, dashboard, floating button, or application shell.

When using a custom launcher, prefer toggle() if the same control should both open and close Messenger.

Listen to Messenger events

The SDK exposes events through on() and off().

For example:

notiondesk.on("messenger:show", () => {
  console.log("Messenger opened");
});

notiondesk.on("messenger:hide", () => {
  console.log("Messenger closed");
});

on() returns an unsubscribe function:

const unsubscribe = notiondesk.on("messenger:show", () => {
  console.log("Messenger opened");
});

// Later
unsubscribe();

Available Messenger events

Track which Messenger section visitors use

The messenger:tabChanged event includes the current and previous tab.

notiondesk.on(
  "messenger:tabChanged",
  ({ tabName, previousTab }) => {
    console.log("Messenger tab:", tabName);
  },
);

For example, you can forward Messenger activity to your analytics platform:

notiondesk.on("messenger:show", () => {
  analytics.track("support_opened");
});

notiondesk.on("messenger:tabChanged", ({ tabName }) => {
  analytics.track("support_tab_opened", {
    tab: tabName,
  });
});

Keep your own launcher synchronized

Events can also synchronize your UI with Messenger state:

notiondesk.on("messenger:show", () => {
  helpButton.setAttribute("aria-expanded", "true");
});

notiondesk.on("messenger:hide", () => {
  helpButton.setAttribute("aria-expanded", "false");
});

Change the Messenger theme

Use setTheme() to switch between light and dark mode without reloading Messenger:

notiondesk.setTheme("dark");

Or:

notiondesk.setTheme("light");

For example, synchronize Messenger with your application's theme:

notiondesk.setTheme(
  isDarkMode ? "dark" : "light",
);

You can also react to operating system theme changes:

const colorScheme = window.matchMedia(
  "(prefers-color-scheme: dark)",
);

function syncMessengerTheme() {
  notiondesk.setTheme(
    colorScheme.matches ? "dark" : "light",
  );
}

syncMessengerTheme();

colorScheme.addEventListener(
  "change",
  syncMessengerTheme,
);

Use the Notiondesk dashboard for your Messenger's colors, fonts, launcher appearance, and other brand settings. The SDK theme control is intended for switching the active color scheme.

Change the Messenger language

Use setLanguage():

notiondesk.setLanguage("fr");

This is useful when your application already has its own language selector:

notiondesk.setLanguage(currentLocale);

The requested locale must be enabled for your Messenger in Notiondesk.

If the locale is not enabled, Messenger keeps an available configured language instead.

Update Messenger after initialization

Use updateConfig() when application state changes after Messenger has already loaded.

Update an authenticated user

After a user signs in:

notiondesk.updateConfig({
  userToken,
});

Messenger updates the current user without requiring a page reload.

Return to an anonymous user

When a user signs out:

notiondesk.updateConfig({
  userToken: null,
});

For the complete authentication flow, see Identify logged-in users in Notiondesk Messenger.

Change the Messenger position

You can move Messenger at runtime:

notiondesk.updateConfig({
  position: "bottom-left",
});

Supported positions are:

• bottom-right

• bottom-left

Your default launcher position should normally be configured in the Notiondesk dashboard. Use updateConfig() when your application needs a temporary runtime override.

For example, you might move Messenger when another floating element occupies the same corner.

Change the stacking level

If Messenger needs to appear above another application element:

notiondesk.updateConfig({
  zIndex: 10000,
});

Use Messenger with authenticated users

Pass a signed user token when initializing Messenger:

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
  userToken,
});

You can also start anonymously and identify the user later:

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

notiondesk.updateConfig({
  userToken,
});

The token must be generated by your backend.

Never expose your Notiondesk App Secret in browser code.

See Identify logged-in users in Notiondesk Messenger for the complete authentication and logout flow.

Remove Messenger

Use destroy() to completely remove the current Messenger instance:

notiondesk.destroy();

Use destroy() when:

• Messenger should no longer exist on the current page

• A user account is being switched

• Your application is unmounting the Messenger integration

• You need to initialize a fresh Messenger session

You can initialize Messenger again after destroying it.

Load Messenger without initializing it

For applications that need more control over initialization, use loadNotiondesk():

import {
  loadNotiondesk,
} from "@notiondesk-so/messenger-js-sdk";

const notiondesk = await loadNotiondesk();

await notiondesk.init({
  messengerId: "YOUR_MESSENGER_ID",
});

Most applications should use initNotiondesk() instead.

loadNotiondesk() is useful when loading the Messenger SDK and starting the Messenger itself need to happen at different points in your application's lifecycle.

Access an already loaded Messenger API

Use getNotiondesk() to synchronously access the API when Messenger has already been loaded:

import {
  getNotiondesk,
} from "@notiondesk-so/messenger-js-sdk";

getNotiondesk()?.show();

If Messenger has not loaded yet, getNotiondesk() returns null.

For normal application initialization, prefer initNotiondesk().

React controls and state

React applications should use:

import {
  NotiondeskProvider,
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/react";

useNotiondesk() provides both Messenger controls and its current loading state.

For example:

function SupportButton() {
  const {
    show,
    status,
  } = useNotiondesk();

  return (
    <button
      disabled={status !== "ready"}
      onClick={() => void show()}
    >
      Contact support
    </button>
  );
}

Available values include:

Use api when you need APIs such as event subscriptions:

import { useEffect } from "react";
import { useNotiondesk } from "@notiondesk-so/messenger-js-sdk/react";

function MessengerAnalytics() {
  const { api } = useNotiondesk();

  useEffect(() => {
    if (!api) {
      return;
    }

    return api.on("messenger:show", () => {
      analytics.track("support_opened");
    });
  }, [api]);

  return null;
}

Keep configuration props such as theme and locale stable on NotiondeskProvider when possible.

For runtime changes, prefer setTheme(), setLanguage(), or updateConfig() rather than repeatedly changing provider configuration.

Vue controls and state

Vue applications can access Messenger using:

import {
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/vue";

For example:

<script setup lang="ts">
import {
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/vue";

const {
  show,
  showTab,
  isReady,
} = useNotiondesk();
</script>

<template>
  <button
    :disabled="!isReady"
    @click="show()"
  >
    Contact support
  </button>

  <button @click="showTab('changelog')">
    What's new
  </button>
</template>

The Vue integration also exposes the Messenger API, status, errors, and the same runtime controls as the core SDK.

Common SDK recipes

Create a custom Help button

Turn off the default launcher in your Notiondesk Messenger settings:

helpButton.addEventListener("click", () => {
  void notiondesk.toggle();
});

Open your help center directly

notiondesk.showTab("help");

Open your AI assistant directly

notiondesk.showTab("messages");

The Messages module must be enabled and configured in Messenger.

Open your contact form directly

notiondesk.showTab("contact");

Open your changelog from a “What's new” link

notiondesk.showTab("changelog");

Hide Messenger on a specific application route

if (window.location.pathname.startsWith("/checkout")) {
  await notiondesk.hide();
}

Move Messenger away from another floating element

notiondesk.updateConfig({
  position: "bottom-left",
});

Track Messenger usage

notiondesk.on("messenger:show", () => {
  analytics.track("support_opened");
});

notiondesk.on("messenger:tabChanged", ({ tabName }) => {
  analytics.track("support_section_opened", {
    section: tabName,
  });
});

Update Messenger after login

notiondesk.updateConfig({
  userToken,
});

Clear the user after logout

notiondesk.updateConfig({
  userToken: null,
});

Troubleshooting

try {
  const notiondesk = await initNotiondesk({
    messengerId: "YOUR_MESSENGER_ID",
  });
} catch (error) {
  console.error(
    "Could not initialize Notiondesk Messenger",
    error,
  );
}

notiondesk.updateConfig({
  zIndex: 10000,
});

notiondesk.updateConfig({
  userToken: null,
});

notiondesk.destroy();

const { show, status } = useNotiondesk();

return (
  <button
    disabled={status !== "ready"}
    onClick={() => void show()}
  >
    Contact support
  </button>
);