react-use-intercom

react-use-intercom

A React Intercom integration focused on developer experience.

Features

• Hooks
• Written in TypeScript
• Documented, self explaining methods
• Tiny size without any external libraries

Installation

yarn add react-use-intercom

Quickstart

import * as React from 'react';

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

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>;
};

Links

• API
• Playground
• TypeScript
• Advanced

API

• IntercomProvider
• useIntercom

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.

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, unreadMessagesCount] = 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');
    unreadMessagesCount(amount);
    console.log('New amount of unread messages: ', unreadMessagesCount);
  };

  return (
    <IntercomProvider
      appId={INTERCOM_APP_ID}
      onHide={onHide}
      onShow={onShow}
      onUnreadCountChange={onUnreadCountChange}
      autoBoot
    >
      <p>Hi there, I'm 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.

Remark - make sure IntercomProvider is wrapped around your component when calling useIntercom()

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-use-intercom';

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' });
  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>
    </>
  );
};

Playground

TypeScript

All the possible pre-defined options to pass to the Intercom instance are typed. So whenever you have to pass IntercomProps, all the possible properties will be available out of the box. These props are JavaScript 'friendly', so camelCase. No need to pass the props with snake_cased keys.

Remark - if you want to pass custom properties, you should still use snake_cased keys.

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-use-intercom';

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>;
};