How to install Notiondesk Messenger with React and Next.js

Notiondesk provides an official JavaScript SDK for installing Messenger in React and Next.js applications.

Use the SDK instead of the standard Messenger <script> snippet when your website is built with React, Next.js, or another single-page application.

Before you start

You need:

A Notiondesk Messenger configured in your workspace

Your Messenger ID

A React or Next.js application

Access to your application's source code

You can find your Messenger ID and installation options in your Notiondesk Messenger settings.

Install the Messenger SDK

Install the official package:

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

With Yarn:

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

With pnpm:

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

The official package is available on npm.

Install Messenger in React

Import NotiondeskProvider and wrap the part of your application where Messenger should be available.

For most applications, place the provider near the root of your app:

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

export function App({ children }) {
  return (
    <NotiondeskProvider messengerId="YOUR_MESSENGER_ID">
      {children}
    </NotiondeskProvider>
  );
}

Replace YOUR_MESSENGER_ID with the Messenger ID from your Notiondesk workspace.

Messenger is now available to components rendered inside NotiondeskProvider.

Open Messenger from a React component

Use the useNotiondesk hook when you need to control Messenger from your interface.

For example, you can create your own support button:

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

export function SupportButton() {
  const { show } = useNotiondesk();

  return (
    <button onClick={() => void show()}>
      Contact support
    </button>
  );
}

The component using useNotiondesk must be rendered inside NotiondeskProvider.

Install Messenger in Next.js

Notiondesk Messenger runs in the browser, so the Messenger integration must be initialized from a client component.

The following example uses the Next.js App Router.

1. Create a Notiondesk client component

Create a component such as notiondesk-setup.tsx:

"use client";

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

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

  return (
    <button onClick={() => void show()}>
      Contact support
    </button>
  );
}

export function NotiondeskSetup({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <NotiondeskProvider messengerId="YOUR_MESSENGER_ID">
      {children}
      <SupportButton />
    </NotiondeskProvider>
  );
}

Replace YOUR_MESSENGER_ID with your Notiondesk Messenger ID.

2. Add the provider to your layout

Render the client component from your root layout:

import { NotiondeskSetup } from "./notiondesk-setup";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <NotiondeskSetup>
          {children}
        </NotiondeskSetup>
      </body>
    </html>
  );
}

Putting NotiondeskSetup in the root layout makes Messenger available throughout the application.

If Messenger should only be available on specific parts of your application, place the provider in a more specific layout or page instead.

Control Messenger programmatically

The React hook exposes Messenger controls that you can use from your components.

For example:

const notiondesk = useNotiondesk();

await notiondesk.show();
await notiondesk.hide();
await notiondesk.toggle();

You can use these methods to connect Messenger to your own buttons, navigation, support menus, or other application UI.

The SDK also supports additional configuration and controls such as changing the language or theme.

Conditionally load Messenger

You can prevent Messenger from loading for users who should not have access to it with the enabled option:

<NotiondeskProvider
  messengerId="YOUR_MESSENGER_ID"
  enabled={currentUser.canUseSupportWidget}
>
  {children}
</NotiondeskProvider>

Keep your application's own permission logic responsible for deciding whether Messenger should be enabled.

This is useful when Messenger should only be available to logged-in customers, specific plans, or particular areas of your application.

Identify logged-in users

Notiondesk Messenger can identify authenticated users by using a signed user token generated by your backend.

Pass the token to the provider:

<NotiondeskProvider
  messengerId="YOUR_MESSENGER_ID"
  userToken={userToken}
>
  {children}
</NotiondeskProvider>

Never expose your Notiondesk App Secret in React or other browser code.

The App Secret must remain on your server. Your frontend should receive only the signed, short-lived user token generated by your backend.

Verify the installation

After installing the SDK:

Start or deploy your application.

Open a page rendered inside NotiondeskProvider

Confirm that Messenger loads correctly

If you added a custom support button, click it and confirm that Messenger opens

Test navigation between pages in your application

Check the browser console for JavaScript errors

For Next.js, also test a production build because client/server rendering behavior can differ from local development.

Troubleshooting

`window is not defined` or `document is not defined`

Notiondesk Messenger must run in the browser.

In Next.js, put the Messenger integration inside a client component using:

"use client";

Do not initialize the Messenger SDK from a Server Component or during server-side rendering.

`useNotiondesk` does not work

useNotiondesk must be used inside a component rendered below NotiondeskProvider.

For example:

<NotiondeskProvider messengerId="YOUR_MESSENGER_ID">
  <SupportButton />
</NotiondeskProvider>

Using the hook outside the provider will not give the component access to the Messenger instance.

Messenger does not load

Check that:

@notiondesk-so/messenger-js-sdk is installed

Your messengerId is correct

NotiondeskProvider is actually rendered on the current page

The provider is enabled if you use the enabled option

The integration runs in the browser

Your browser console does not show JavaScript or network errors

Copy your Messenger ID directly from Notiondesk to avoid using an ID from another workspace or Messenger.

Messenger disappears on some pages

Messenger is only available inside the part of the React component tree wrapped by NotiondeskProvider.

Place the provider in your root application component or root Next.js layout if Messenger should remain available throughout the application.

A custom support button does not open Messenger

Confirm that the component calling useNotiondesk() is rendered inside NotiondeskProvider.

Then confirm that show() is called from the button action:

const { show } = useNotiondesk();

<button onClick={() => void show()}>
  Contact support
</button>

Table of contents