react-use-intercom

A React Intercom integration powered by hooks.

Features

• Hooks
• Written in TypeScript
• Documented, self explaining methods
• Tiny size without any external libraries
• Safeguard for SSR environments (NextJS, Gatsby)
• Compatible to hook into existing Intercom instance (loaded by Segment)

Installation

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

Quickstart

import*asReactfrom'react';import{IntercomProvider,useIntercom}from'react-use-intercom';constINTERCOM_APP_ID='your-intercom-app-id';constApp=()=>(<IntercomProviderappId={INTERCOM_APP_ID}><HomePage/></IntercomProvider>);// Anywhere in your appconstHomePage=()=>{const{ boot, shutdown, hide, show, update }=useIntercom();return<buttononClick={boot}>Bootintercom!☎️</button>;};

Context

This library is a React abstraction of IntercomJS. react-use-intercom tries to keep as close as a one-on-one abstraction of the "vanilla" Intercom functionality.

Note that many issues could be related to the vanilla IntercomJS library. Please see https://community.intercom.com/ before reporting an issue here.

Links

• API
• Playground
• Examples
• TypeScript
• Troubleshoot
• Advanced

API

• IntercomProvider
• useIntercom
• IntercomProps

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 call 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
onUserEmailSupplied	() => void	triggered when a visitor enters their email into the Messenger	false
shouldInitialize	boolean	indicates if the Intercom should be initialized. Can be used in multistaged environment	false	true
apiBase	string	If you need to route your Messenger requests through a different endpoint than the default. Generally speaking, this is not needed. Format: https://${INTERCOM_APP_ID}.intercom-messenger.com (See: #96)	false
initializeDelay	number	Indicates if the intercom initialization should be delayed, delay is in ms, defaults to 0. See #236	false
autoBootProps	IntercomProps	Pass properties to boot method when autoBoot is true	false
crossOrigin	'anonymous' | 'use-credentials' | ''	Sets the crossOrigin attribute on the Messenger <script> (standard DOM attribute, not an Intercom API). Use 'anonymous' for full error details in error logging; works because Intercom's CDN allows CORS	false
onLoad	() => void	triggered when the Messenger script has loaded successfully	false
onLoadFailed	() => void	triggered when the Messenger script has failed to load (network issues, Intercom downtime, firewall, blocking browser extensions, ...)	false

Example

constApp=()=>{const[unreadMessagesCount,setUnreadMessagesCount]=React.useState(0);constonHide=()=>console.log('Intercom did hide the Messenger');constonShow=()=>console.log('Intercom did show the Messenger');constonUnreadCountChange=(amount: number)=>{console.log('Intercom has a new unread message');setUnreadMessagesCount(amount);};constonUserEmailSupplied=()=>{console.log('Visitor has entered email');};return(<IntercomProviderappId={INTERCOM_APP_ID}onHide={onHide}onShow={onShow}onUnreadCountChange={onUnreadCountChange}onUserEmailSupplied={onUserEmailSupplied}autoBoot><p>Hithere,IamachildoftheIntercomProvider</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.

API

name	type	description
isOpen	boolean	the visibility status of the messenger
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
showNewMessage	(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
startConversation	(message: string) => void	opens the Messenger and immediately starts a new conversation with the supplied message
getVisitorId	() => string	gets the visitor id
startTour	(tourId: number) => void	starts a tour based on the tourId
startChecklist	(checklistId: number) => void	starts a checklist based on the checklistId
trackEvent	(event: string, metaData?: object) => void	submits an event with optional metaData
showArticle	(articleId: string) => void	opens the Messenger with the specified article by articleId
startSurvey	(surveyId: number) => void	Trigger a survey in the Messenger by surveyId
showSpace	(spaceName: IntercomSpace) => void	Opens the Messenger with the specified space
showNews	(newsId: number) => void	Opens the Messenger with the specified news item by newsId
showTicket	(ticketId: number) => void	Opens the Messenger with the specified ticket by ticketId
showConversation	(conversationId: number) => void	Opens the Messenger with the specified conversation by conversationId
hideNotifications	(hidden: boolean) => void	controls the visibility of in-app notifications, pass true to hide or false to show them
setAuthTokens	(authTokens: AuthTokens) => void	sets/refreshes the per-user Data Connector auth tokens at runtime without a full update

Example

import*asReactfrom'react';import{IntercomProvider,useIntercom}from'react-use-intercom';constINTERCOM_APP_ID='your-intercom-app-id';constApp=()=>(<IntercomProviderappId={INTERCOM_APP_ID}><HomePage/></IntercomProvider>);constHomePage=()=>{const{
boot,
shutdown,
hardShutdown,
update,
hide,
show,
showMessages,
showNewMessage,
startConversation,
getVisitorId,
startTour,
startChecklist,
trackEvent,
showArticle,
startSurvey,
showSpace,
showNews,
showTicket,
showConversation,
hideNotifications,
setAuthTokens,}=useIntercom();constbootWithProps=()=>boot({name: 'Russo'});constupdateWithProps=()=>update({name: 'Ossur'});consthandleNewMessages=()=>showNewMessage();consthandleNewMessagesWithContent=()=>showNewMessage('content');consthandleStartConversation=()=>startConversation('Hello');consthandleGetVisitorId=()=>console.log(getVisitorId());consthandleStartTour=()=>startTour(123);consthandleStartChecklist=()=>startChecklist(456);consthandleTrackEvent=()=>trackEvent('invited-friend');consthandleTrackEventWithMetaData=()=>trackEvent('invited-frind',{name: 'Russo',});consthandleShowArticle=()=>showArticle(123456);consthandleStartSurvey=()=>startSurvey(123456);consthandleShowSpace=()=>showSpace('tasks');consthandleShowNews=()=>showNews(123);consthandleShowTicket=()=>showTicket(123);consthandleShowConversation=()=>showConversation(123);consthandleHideNotifications=()=>hideNotifications(true);consthandleSetAuthTokens=()=>setAuthTokens({security_token: 'your-jwt'});return(<><buttononClick={boot}>Bootintercom</button><buttononClick={bootWithProps}>Bootwithprops</button><buttononClick={shutdown}>Shutdown</button><buttononClick={hardShutdown}>Hardshutdown</button><buttononClick={update}>Updatecleansession</button><buttononClick={updateWithProps}>Updatesessionwithprops</button><buttononClick={show}>Showmessages</button><buttononClick={hide}>Hidemessages</button><buttononClick={showMessages}>Showmessagelist</button><buttononClick={handleNewMessages}>Shownewmessages</button><buttononClick={handleNewMessagesWithContent}>Shownewmessagewithpre-filledcontent</button><buttononClick={handleStartConversation}>Startconversation</button><buttononClick={handleGetVisitorId}>Getvisitorid</button><buttononClick={handleStartTour}>Starttour</button><buttononClick={handleStartChecklist}>Startchecklist</button><buttononClick={handleTrackEvent}>Trackevent</button><buttononClick={handleTrackEventWithMetaData}>Trackeventwithmetadata</button><buttononClick={handleShowArticle}>OpenarticleinMessenger</button><buttononClick={handleStartSurvey}>StartsurveyinMessenger</button><buttononClick={handleShowSpace}>OpenspaceinMessenger</button><buttononClick={handleShowNews}>OpennewsinMessenger</button><buttononClick={handleShowTicket}>OpenticketinMessenger</button><buttononClick={handleShowConversation}>OpenconversationinMessenger</button><buttononClick={handleHideNotifications}>Hidenotifications</button><buttononClick={handleSetAuthTokens}>Setauthtokens</button></>);};

IntercomProps

All the Intercom default attributes/props are camel cased (appId instead of app_id) in react-use-intercom, see IntercomProps to see what attributes you can pass to boot or update. Or check the Intercom docs to see all the available attributes/props.

Remark - all the listed Intercom attributes here are snake cased, in react-use-intercom these are camel cased.

Custom attributes

Still want to pass custom attributes to Intercom? Whether boot or update is used, you can add your custom properties by passing these through customAttributes in the boot or update method.

Remark - the keys of the customAttributes object should be snake cased (this is how Intercom wants them). They are rawly passed to Intercom.

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

Authentication tokens

For secure data operations, you can pass authentication tokens to Intercom using the authTokens property. This accepts an object with any string key-value pairs.

const{ boot }=useIntercom();boot({email: 'john.doe@example.com',userId: '9876',authTokens: {security_token: 'abc...',// JWT tokenapi_token: 'xyz...',// Any other tokens as key-value pairs}})

This is distinct from intercomUserJwt, which is for Messenger identity verification. To refresh a token during a session without sending a full update, use the setAuthTokens method:

const{ setAuthTokens }=useIntercom();setAuthTokens({security_token: 'refreshed-jwt'});

Playground

Small playground to showcase the functionalities of react-use-intercom.

useIntercom

https://devrnt.github.io/react-use-intercom/#/useIntercom

useIntercom (with Intercom tour)

https://devrnt.github.io/react-use-intercom/#/useIntercomTour

Examples

Go to examples to check out some integrations (Gatsby, NextJS...).

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.

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.

• I'm seeing Some invalid props were passed to IntercomProvider. Please check following props: [properties] in the console.

Make sure you're passing the correct properties to the IntercomProvider. Check IntercomProvider to see all the properties. Mind that all the properties in react-use-intercom are camel cased, except for the customAttributes property in the boot and update method from useIntercom.

Advanced

Delay initialization

<IntercomProvider /> uses an official intercom snippet and is directly initialized on load. In the background this snippet will load some external code that makes Intercom work. All of this magic happens on the initial load and in some use cases this can become problematic (E.g. when LCP is priority).

Since v1.2.0 it's possible to delay this initialisation by passing initializeDelay in <IntercomProvider /> (it's in milliseconds). However most of the users won't need to mess with this.

For reference see #236 and https://forum.intercom.com/s/question/0D52G00004WxWLs/can-i-delay-loading-intercom-on-my-site-to-reduce-the-js-load

Detect a broken Messenger

The Messenger script can fail to load for various reasons, e.g. network issues, Intercom downtime, firewall rules, or browser extensions like tracking blockers.

Pass onLoadFailed to <IntercomProvider /> to detect when that happens and offer the user an alternative support channel. Use onLoad to know when the script loaded successfully (e.g. to hide a loading state).

<IntercomProviderappId={INTERCOM_APP_ID}onLoad={()=>console.log('Messenger loaded')}onLoadFailed={()=>console.log('Messenger failed to load')}>
...
</IntercomProvider>

Pass crossOrigin="anonymous" to unlock full error details for errors thrown by the Messenger loader script — a standard <script> attribute rather than an Intercom feature. It works because Intercom's CDN serves the script with permissive CORS headers.

Contributing

Contributions are welcome! Please read the Contributing Guidelines for details on how to contribute to the project.