react-intercom-hook

!CI
!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

`js
import * as React from 'react';

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

const INTERCOM_APP_ID = 'your-intercom-app-id';

const App = () => (



);

// Anywhere in your app
const HomePage = () => {
const { boot, shutdown, hide, show, update } = useIntercom();

return Boot intercom! ☎️;
};
`

Links

- API
- Playground
- Troubleshoot
- Advanced

API

- IntercomProvider
- useIntercom

$3

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

`javascript
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 (
appId={INTERCOM_APP_ID}
onHide={onHide}
onShow={onShow}
onUnreadCountChange={onUnreadCountChange}
autoBoot
>


Hi there, I am a child of the IntercomProvider

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

`javascript
import * as React from 'react';

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

const INTERCOM_APP_ID = 'your-intercom-app-id';

const App = () => (



);

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 (
<>
Boot intercom
Boot with props
Shutdown
Hard shutdown
Update clean session
Update session with props
Show messages
Hide messages
Show message list
Show new messages

Show new message with pre-filled content

Get visitor id
Start tour
Track event

Track event with metadata


);
};
`

#### 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.

`javascript
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.

$3

`javascript
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 (



);
};

const HomePage = () => {
const { boot } = useIntercom();

// const bootWithProps = () => boot({ name: 'Russo' });
const bootWithProps = React.useCallback(() => boot({ name: 'Russo' }), [
boot,
]);

return Boot with props;
};
`

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.