Skip to content

multivoltage/react-use-zendesk

Repository files navigation

react-use-zendesk

React Zendesk Web Widget integration written in typescript.

version

Features

  • Web Widget api available. Please see Zendesk docs
  • TypeScript support
  • Only 25kb
  • Working on NextJS/Gatsby

⚠️ Web widget vs Web Widget (classic) ⚠️

This library offers API only for the new version called Web widget. For more information please read the comparison

Installation

npm i react-use-zendesk

Usage

import { ZendeskProvider, useZendesk } from 'react-use-zendesk';

const App = () => (
  <ZendeskProvider apiKey={process.env.API_KEY || ""}>
    <Home />
  </ZendeskProvider>
);

const Home = () => {
  const { open, unreadMessages } = useZendesk();

  return <div>
	  you have ${unreadMessages} messages!
	 <button onClick={open}>Open chat now</button>
  </div>;
};

API

ZendeskProvider

library uses ZendeskProvider to initialize the window.zE instance. If any listeners are passed, the provider will make sure these callbacks are attached.

Place the ZendeskProvider as high as possible in your application. This will make sure you can call useZendesk anywhere. Remember that the provider under the hood use React.context, so in Next JS you have to declare "use client" for the component.

Props

name type description required default
apiKey string api key of your Zendesk account X
children React.ReactNode React children true
onOpen () => void triggered when the Widget opens (chat is visible). Please see isOpen field if you want to get chat state by hooks
onClose () => void triggered when the Widget closes (chat is hidden). Please see isOpen field if you want to get chat state by hooks
onUnreadMessages (count; number) => void triggered when the current number of unread messages changes. If attached, Zendesk triggers this callback after initialization. Please see unreadMessages field if you want to get the number by hook

Example

const App = () => {
  const handleOpen = () => console.log('Chat become visible');
  const handleClose = () => console.log('Chat become hidden');
  const handleUnreadMessages = (count: number) => console.log('You have',count,'messages to read');
  
  return (
    <ZendeskProvider
		apiKey={process.env.KEY || ""}
		onOpen={handleOpen}
		onClose={handleClose}
		onUnreadMessages={handleUnreadMessages}
    >
      <p>fake child example</p>
    </ZendeskProvider>
  );
};

useZendesk

Used to retrieve all methods bundled with Zendesk Web Widget. These are based on the official Zendesk docs. For each api if you want to get more details please refer to Zendesk Docs. Library add some useful fields.

Make sure ZendeskProvider is wrapped around your component when calling useZendesk().

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

API

name type description
isOpen boolean the visibilty status if chat. If you call open after hide this flag will be false
show () => void Displays the widget. The widget is displayed by default on page load. You don't need to call show to display the widget unless you use hide.
hide () => void Hides all parts of the widget from the page. You can invoke it before or after page load.
open () => void Opens the messaging Web Widget. Chat become visible
close () => void Closes the messaging Web Widget
setLocale (newLocale: string) => void Sets the locale of the messaging Web Widget.
setZIndex (newZIndex: number) => void Sets the CSS property z-index on all the iframes for the messaging WebWidget.
setCookies (isEnabled: boolean) => void The messaging Web Widget uses a mixture of cookies as well as local and session storage in order to function.
setConversationFields (conversationFields: ZendeskConversationField[]) => void Allows values for conversation fields to be set in the client to add contextual data about the conversation.
setConversationTags (conversationTags: string[]) => void Allows custom conversation tags to be set in the client to add contextual data about the conversation
loginUser (jwtToken: string) => void If your application has a login flow, or if a user needs to access the same conversation from multiple devices
logoutUser () => void Your app may have a logout function that brings users back to a login screen. In this case, revert the messaging Web Widget to a pre-login state
isOpen boolean this flag indicates if chat is visible or hidden. Derivated from from onOpen and onCLose
unreadMessages number / undefined this flag indicates number of unread messages . Derivated from from onUnreadMessages. Before internal callback this flag is undefined

Example

import { ZendeskProvider, useZendesk } from 'react-use-zendesk';

const App = () => (
  <ZendeskProvider apiKey={process.env.KEY || ""}>
    <Home />
  </ZendeskProvider>
);

const Home = () => {
  const {
    open,
    close,
    isOpen,
    unreadMessages,
    setLocale
  } = useZendesk();

  const changeLocale = () => setLocale("es")
  
  return (
    <>
	  <p>you have {unreadMessages} unread messages</p>
	  <p>your chat is ${isOpen ? "visible" : "hidden"}</p>
      <button onClick={changeLocale}>Set ES as locale</button>   
    </>
  );
};

Examples

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