React Live Chat Loader

An npm module that allows you to mitigate the negative performance and user experience impact of chat tools. react-live-chat-loader shows a fake widget until the page has become idle or users are ready to interact with chat. Currently works with Intercom, Help Scout, Drift, Messenger, Userlike, Front, Chatwoot and Hubspot.

Made by the team at ♠ Calibre, your performance companion.

[!IMPORTANT]
This project is looking for collaborators, maintainers and/or new stewardship.

Since introducing react-live-chat-loader in 2019 we've welcomed the addition of several chat provider tools, with thanks to numerous contributors. As a group the Calibre team have taken this library as far as we can, and we're looking for someone to take the reigns. If you, your buddies or team can help, please create a new issue to start discussion. 💬

🖇️ Table of Contents

1. How it Works
2. Installation
3. Usage
4. Supported Providers
5. Adding a Provider
6. Examples
7. Contributing
8. Resources
9. License

💡 How it Works

Chat widgets rely heavily on JavaScript which comes at a cost. Given the significant impact that comes from the download, parse, compile and execution of chat JavaScript, React Live Chat Loader implements a "fake", fast loading button and waits for one of the following events before loading the actual widget:

• Person hovers over the fake button
• Person clicks the fake button
• The page has been idle for a significant amount of time

Under the hood React Live Chat Loader makes use of requestIdleCallback to track how long the page has been idle for and checks if the person is on a slow connection (using navigator.connection.effectiveType) or has data-saver enabled (using navigator.connection.saveData) to prevent loading.

⚠️ Please note: Some chat widget providers open automatically based on the people’s interaction from their last session.

📥 Installation

To download react-live-chat-loader run:

npm install --save react-live-chat-loader

Or if you're using yarn, run:

yarn add react-live-chat-loader

🛠 Usage

To allow you to trigger a single live chat within your application, React Live Chat Loader has a Context Provider which should be added at the root level of your application.

You pass your providerKey and provider to the LiveChatLoaderProvider.

For example, to add a LiveChatLoaderProvider for Help Scout you would do the following:

import { LiveChatLoaderProvider } from 'react-live-chat-loader'

export default class App extends React.Component {
  /* ... */

  render() {
    return (
      <LiveChatLoaderProvider providerKey="asdjkasl123123" provider="helpScout">
        /* ... */
      </LiveChatLoaderProvider>
    )
  }
}

You can then include the relevant chat where you would like it to appear.

For example, for Help Scout you would import the HelpScout component and add it to your application:

import { HelpScout } from 'react-live-chat-loader'

export default class Index extends React.Component {
  /* ... */

  render() {
    return (
      <>
        /* ... */
        <HelpScout />
      </>
    )
  }
}

To display chat from a custom button you can import the useChat hook which has the current state of the chat and a function to load the chat.

import { useChat } from 'react-live-chat-loader'

export const LoadChatButton = () => {
  const [state, loadChat] = useChat()

  return <button onClick={() => loadChat({ open: true })}>Load Chat</button>
}

Options

You can pass the following props to the LiveChatLoaderProvider provider:

• provider: Choose from helpScout, intercom, drift, front or messenger (see below)
• providerKey: Provider API Key (see below)
• idlePeriod: How long to wait in ms before loading the provider. Default is 2000. Set to 0 to never load. This value is used in a setTimeout in browsers that don't support requestIdleCallback.
• beforeInit: A function to be called after the script has loaded, but before the chat provider has been initialized (optional)
• onReady: A function to be called once the script has been loaded, the chat provider has been initialized and is ready for use (optional)

💬 Supported Providers

Currently there are eight supported providers:

➕ Adding a Provider

To add a new live chat provider, follow the steps in Contributing: Adding a Provider.

🖥️ Examples

The website directory of this repository includes a Next.js app with example implementations of all currently supported providers.

For the initial setup of the example app, be sure first to run npm install + npm run build in the root level of the repository before running npm install in the website directory.

The following scripts in the example app will then be available:

• npm run dev (run a local server)
• npm run build (run next build)
• npm run start (run next start)

Visit react-live-chat-loader.vercel.app for a hosted version of the example app.

📝  Note that some providers require safe-listed, publicly accessible domains served over HTTPS — a service like ngrok can help achieve this locally.

🙌 Contributing

Happy to hear you’re interested in contributing to React Live Chat Loader! Please find our contribution guidelines here.

Past Contributors

Thanks goes to these wonderful people (emoji key):

Kevin Peng 💻	Ash Kyd 📖	Jeff Reiner 📖 💻	Joan Mira 💻	Nathan Collman 💻	Jaakko Mustalahti 💻	Moti Korets 💻
Michael Stramel 💻	Myles Linder 💻	Laura Gutiérrez López de la Franca 💻	Kirill Vakalov 💻	Luís Rudge 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

📚 Resources

• How to avoid performance regressions when using live chat tools
• Reducing the Intercom Messenger bundle size by 65%

💼 License

This project is MIT licensed.