README.md

react-use-zendesk

React Zendesk Web Widget integration written in typescript.

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
• useZendesk

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