React Intercom Integration with Hooks

Common errors

• ReferenceError: window is not defined

  cause Attempting to access browser-specific APIs (like `window`) during server-side rendering without proper checks.
  fix Ensure code interacting with `window` is executed only in the browser context. `react-use-intercom` generally handles this, but custom logic may require `typeof window !== 'undefined'` checks or `useEffect` for client-side execution.

• Error: `useIntercom` must be used within `IntercomProvider`

  cause The `useIntercom` hook was called outside of an `IntercomProvider` context.
  fix Wrap the component that uses `useIntercom` (and its ancestors) with `<IntercomProvider appId="YOUR_APP_ID">...</IntercomProvider>`.

• Content Security Policy (CSP) violation: The page’s settings blocked the loading of a resource at...

  cause Your web application's Content Security Policy is preventing Intercom scripts or resources from loading.
  fix Update your CSP to allow `script-src`, `style-src`, `connect-src`, and other necessary directives from Intercom's domains. For dynamic script injection, you might need to use a `nonce` attribute for scripts.

• TypeError: Cannot read properties of undefined (reading 'boot')

  cause The `boot` method (or any other method from `useIntercom`) was called on an undefined object, likely due to `IntercomProvider` not being ready or `useIntercom` being called too early or out of context.
  fix Verify that `IntercomProvider` is correctly initialized with an `appId` and that `useIntercom` is called within a functional component rendered under `IntercomProvider`. Ensure `IntercomProvider` has had time to initialize on the client side, especially in complex hydration scenarios.

Warnings

• gotcha When deploying with a Content Security Policy (CSP), ensure that your policy allows script sources from Intercom's domains. Recent versions (>=5.4.3) added support for nonces, but proper CSP configuration is still essential for the Intercom widget to load and function correctly.
  Fix: Refer to Intercom's documentation for required CSP directives and ensure your server-side rendering or build process correctly injects nonces into the Intercom script tags if used.
• gotcha In Server-Side Rendering (SSR) environments like Next.js or Gatsby, direct manipulation of the `window` object will cause 'window is not defined' errors. While `react-use-intercom` includes safeguards, ensure you are mindful of client-side-only code and potentially deferring Intercom operations to the browser environment.
  Fix: Place IntercomProvider high in your component tree and ensure any custom logic interacting with `window.Intercom` is wrapped in `typeof window !== 'undefined'` checks or executed in `useEffect` hooks.
• gotcha Many issues encountered with `react-use-intercom` might originate from the underlying IntercomJS library itself, not the React wrapper. The library provides a direct abstraction, so understanding vanilla Intercom functionality is crucial for debugging complex issues.
  Fix: Consult the official Intercom documentation and community forums (community.intercom.com) for issues related to Intercom's core behavior, API limits, or configuration rather than solely focusing on the React wrapper.
• gotcha Forgetting to wrap your application or relevant component tree with `IntercomProvider` will result in `useIntercom` not being able to find the Intercom context, leading to runtime errors.
  Fix: Ensure `IntercomProvider` is placed as high as possible in your React component hierarchy, above any components that call `useIntercom`.

Install

• npm install react-use-intercom npm
• yarn add react-use-intercom yarn
• pnpm add react-use-intercom pnpm

Imports

• IntercomProvider
  wrong:

  const { IntercomProvider } = require('react-use-intercom');

  correct:

  import { IntercomProvider } from 'react-use-intercom';

  IntercomProvider is a named export and should be imported using ES Module syntax. It must wrap any components using useIntercom.
• useIntercom
  wrong:

  const { useIntercom } = require('react-use-intercom');

  correct:

  import { useIntercom } from 'react-use-intercom';

  useIntercom is a named export and a React Hook. It must be called from within a React functional component or custom hook.
• * as IntercomModule
  wrong:

  import IntercomModule from 'react-use-intercom';

  correct:

  import * as IntercomModule from 'react-use-intercom';

  While less common, this imports all named exports into a single object. No default export exists.

Quickstart

This code demonstrates how to initialize Intercom using IntercomProvider, boot the messenger, and control its visibility using the useIntercom hook.

import * as React from 'react';
import { IntercomProvider, useIntercom } from 'react-use-intercom';

const INTERCOM_APP_ID = process.env.INTERCOM_APP_ID ?? 'your-intercom-app-id';

const App = () => (
  <IntercomProvider appId={INTERCOM_APP_ID}>
    <HomePage />
  </IntercomProvider>
);

const HomePage = () => {
  const { boot, shutdown, hide, show, update, showNewMessage } = useIntercom();

  return (
    <div>
      <button onClick={() => boot({ hideDefaultLauncher: false })}>Boot Intercom! ☎️</button>
      <button onClick={hide}>Hide Messenger</button>
      <button onClick={show}>Show Messenger</button>
      <button onClick={() => showNewMessage('Hello there!')}>New Message</button>
      <button onClick={shutdown}>Shutdown Intercom</button>
      <p>This button boots Intercom and shows the messenger. Other buttons control its visibility or initiate new conversations.</p>
    </div>
  );
};

// To run this in a simple environment, you might need a root element and ReactDOM.
// For example, in a Create React App setup:
// import ReactDOM from 'react-dom/client';
// const root = ReactDOM.createRoot(document.getElementById('root'));
// root.render(<App />);