react-intercom-hook

downloads minzipped size

A brand new hassle-free React Intercom integration powered by hooks.

Features

Built for the latest React
Written in TypeScript
React hooks
Documented, self explaining methods
Written without external libraries
Tiny size

Requirements

NodeJS >=10
React >=16

Installation

npm i react-intercom-hook
OR
yarn add react-intercom-hook

Quickstart

import * as React from 'react';
 
import { IntercomProvider, useIntercom } from 'react-intercom-hook';
 
const INTERCOM_APP_ID = 'your-intercom-app-id';
 
const App = () => (
  <IntercomProvider appId={INTERCOM_APP_ID}>
    <HomePage />
  </IntercomProvider>
);
 
// Anywhere in your app
const HomePage = () => {
  const { boot, shutdown, hide, show, update } = useIntercom();
 
  return <button onClick={boot}>Boot intercom! ☎️</button>;
};

IntercomProvider

IntercomProvider is used to initialize the window.Intercom instance. It makes sure the initialization is only done once. If any listeners are passed, the IntercomProvider will make sure these are attached.

Place the IntercomProvider as high as possible in your application. This will make sure you can useIntercom() anywhere.

Props

name	type	description	required	default
appId	string	app ID of your Intercom instance	true
children	React.ReactNode	React children	true
autoBoot	boolean	indicates if Intercom should be automatically booted. If `true` no need to call `boot`, the `IntercomProvider` will call it for you	false	false
onHide	() => void	triggered when the Messenger hides	false
onShow	() => void	triggered when the Messenger shows	false
onUnreadCountChange	(number) => void	triggered when the current number of unread messages changes	false

Example

const App = () => {
  const [unreadMessagesCount, setUnreadMessagesCount] = React.useState(0);
 
  const onHide = () => console.log('Intercom did hide the Messenger');
  const onShow = () => console.log('Intercom did show the Messenger');
  const onUnreadCountChange = (amount: number) => {
    console.log('Intercom has a new unread message');
    setUnreadMessagesCount(amount);
  };
 
  return (
    <IntercomProvider
      appId={INTERCOM_APP_ID}
      onHide={onHide}
      onShow={onShow}
      onUnreadCountChange={onUnreadCountChange}
      autoBoot
    >
      <p>Hi there, I am a child of the IntercomProvider</p>
    </IntercomProvider>
  );
};

useIntercom

Used to retrieve all methods bundled with Intercom. These are based on the official Intercom docs. Some extra methods were added to improve convenience.

Make sure IntercomProvider is wrapped around your component when calling useIntercom().

Remark - You can't use useIntercom() in the same component where IntercomProvider is initialized.

Methods

name	type	description
boot	(props?: IntercomProps) => void	boots the Intercom instance, not needed if `autoBoot` in `IntercomProvider` is `true`
shutdown	() => void	shuts down the Intercom instance
hardShutdown	() => void	same functionality as `shutdown`, but makes sure the Intercom cookies, `window.Intercom` and `window.intercomSettings` are removed.
update	(props?: IntercomProps) => void	updates the Intercom instance with the supplied props. To initiate a 'ping', call `update` without props
hide	() => void	hides the Messenger, will call `onHide` if supplied to `IntercomProvider`
show	() => void	shows the Messenger, will call `onShow` if supplied to `IntercomProvider`
showMessages	() => void	shows the Messenger with the message list
showNewMessages	(content?: string) => void	shows the Messenger as if a new conversation was just created. If `content` is passed, it will fill in the message composer
getVisitorId	() => string	gets the visitor id
startTour	(tourId: number) => void	starts a tour based on the `tourId`
trackEvent	(event: string, metaData?: object) => void	submits an `event` with optional `metaData`

Example

import * as React from 'react';
 
import { IntercomProvider, useIntercom } from 'react-intercom-hook';
 
const INTERCOM_APP_ID = 'your-intercom-app-id';
 
const App = () => (
  <IntercomProvider appId={INTERCOM_APP_ID}>
    <HomePage />
  </IntercomProvider>
);
 
const HomePage = () => {
  const {
    boot,
    shutdown,
    hardShutdown,
    update,
    hide,
    show,
    showMessages,
    showNewMessages,
    getVisitorId,
    startTour,
    trackEvent,
  } = useIntercom();
 
  const bootWithProps = () => boot({ name: 'Russo' });
  const updateWithProps = () =>
    update({ name: 'Ossur', language_override: 'en' });
  const handleNewMessages = () => showNewMessages();
  const handleNewMessagesWithContent = () => showNewMessages('content');
  const handleGetVisitorId = () => console.log(getVisitorId());
  const handleStartTour = () => startTour(123);
  const handleTrackEvent = () => trackEvent('invited-friend');
  const handleTrackEventWithMetaData = () =>
    trackEvent('invited-frind', {
      name: 'Russo',
    });
 
  return (
    <>
      <button onClick={boot}>Boot intercom</button>
      <button onClick={bootWithProps}>Boot with props</button>
      <button onClick={shutdown}>Shutdown</button>
      <button onClick={hardShutdown}>Hard shutdown</button>
      <button onClick={update}>Update clean session</button>
      <button onClick={updateWithProps}>Update session with props</button>
      <button onClick={show}>Show messages</button>
      <button onClick={hide}>Hide messages</button>
      <button onClick={showMessages}>Show message list</button>
      <button onClick={handleNewMessages}>Show new messages</button>
      <button onClick={handleNewMessagesWithContent}>
        Show new message with pre-filled content
      </button>
      <button onClick={handleGetVisitorId}>Get visitor id</button>
      <button onClick={handleStartTour}>Start tour</button>
      <button onClick={handleTrackEvent}>Track event</button>
      <button onClick={handleTrackEventWithMetaData}>
        Track event with metadata
      </button>
    </>
  );
};

Custom attributes

Still want to pass custom attributes to Intercom? Whether boot or update is used, you can add your custom properties by passing them alongside your other properties. They are rawly passed to Intercom.

const { boot } = useIntercom();
 
boot({
  name: 'Russo',
  custom_attribute_key: 'hi there',
});

Playground

Example playground to showcase the functionalities of react-intercom-hook.

useIntercom useIntercom (with Intercom tour)

Troubleshoot

I'm seeing "Please wrap your component with IntercomProvider." in the console.

Make sure IntercomProvider is initialized before calling useIntercom(). You only need to initialize IntercomProvider once. It is advised to initialize IntercomProvider as high as possible in your application tree.

Make sure you aren't calling useIntercom() in the same component where you initialized IntercomProvider.

Advanced

To reduce the amount of re-renders in your React application I suggest to make use of useCallback

TLDR: useCallback will return a memoized version of the callback that only changes if one of the dependencies has changed.

This can be applied to both the IntercomProvider events and the useIntercom methods. It depends on how many times your main app gets re-rendered.

Example

import * as React from 'react';
 
import { IntercomProvider, useIntercom } from 'react-intercom-hook';
 
const INTERCOM_APP_ID = 'your-intercom-app-id';
 
const App = () => {
  // const onHide = () => console.log('Intercom did hide the Messenger');
  const onHide = React.useCallback(
    () => console.log('Intercom did hide the Messenger'),
    [],
  );
 
  return (
    <IntercomProvider appId={INTERCOM_APP_ID} onHide={onHide}>
      <HomePage />
    </IntercomProvider>
  );
};
 
const HomePage = () => {
  const { boot } = useIntercom();
 
  // const bootWithProps = () => boot({ name: 'Russo' });
  const bootWithProps = React.useCallback(() => boot({ name: 'Russo' }), [
    boot,
  ]);
 
  return <button onClick={bootWithProps}>Boot with props</button>;
};

Copyright/Variations

This package was forked from devrnt's react-use-intercom. One of the key differences between this package and the original is snake casing vs. camel casing of Intercom props.

In react-use-intercom, all of Intercom's non-custom variables are expected to be passed in as camel-cased format. However, as Intercom expects snake-casing instead (and due to the lack of documentation indicating the camel-casing requirement), this led to various issues caused by the mapping between the two casing styles, namely disallowing snake-casing entirely and removing custom variables. Due to the lack of maintainer support, I decided to fork it as a new package.

react-intercom-hook

react-intercom-hook

Features

Requirements

Installation

Quickstart

Links

API

IntercomProvider

Props

Example

useIntercom

Methods

Example

Custom attributes

Playground

Troubleshoot

Advanced

Example

Copyright/Variations

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

react-intercom-hook

react-intercom-hook

Features

Requirements

Installation

Quickstart

Links

API

IntercomProvider

Props

Example

useIntercom

Methods

Example

Custom attributes

Playground

Troubleshoot

Advanced

Example

Copyright/Variations

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads