React Live Chat from Customerly

Enhance your React application with Customerly's powerful Live Chat system. Leverage advanced features such as real-time
user authentication, customized user attributes, and extensive interaction capabilities.


Features

* Real-time user authentication
* Customizable user attributes for enhanced personalization
* Dynamic interaction with programmable buttons
* Fully compatible with SSR environments like NextJS
* Lightweight with no external dependencies

Installation

``bash
npm install --save react-live-chat-customerly


or

yarn add react-live-chat-customerly

or

pnpm add react-live-chat-customerly
`

Quickstart

`tsx
import React, {FunctionComponent, useEffect} from 'react';
import {CustomerlyProvider, useCustomerly} from 'react-live-chat-customerly';

const PROJECT_ID = 'YOUR_CUSTOMERLY_PROJECT_ID';

const App: FunctionComponent = () => (



);

const HomePage: FunctionComponent = () => {
const {load, open} = useCustomerly();

// Automatically load the chat when the component mounts
useEffect(() => {
load();
}, []);

// Button to open the chat interface
const handleOpenChat = () => {
open();
};

return (

Open Chat

);
};

export default App;
`

API Reference

$3

Sets up the Customerly chat environment.

#### CustomerlyProvider Props

| Prop | Type | Description | Required | Default |
|-------|---------|------------------------------------------|----------|---------|
| appId | string | Your Customerly Project ID | Yes | None |
| beta | boolean | Enable the beta version of the messenger | No | false |

> ⚠️ Note: Activating the beta flag allows you to try our newest features before their official release. Please be aware
> that these features are in beta and may be less stable. Your feedback is valuable in helping us improve.

$3

Hook to interact with Customerly chat functionalities.

#### Functions

| Function | Arguments | Description |
| ------------------------------ | -------------------------------------------- | ---------------------------------------------------------- |
| load | load options | Initializes and loads the chat window with user data |
| update | update options | Updates the chat window with new user data |
| open | None | Opens the chat window |
| close | None | Closes the chat window |
| show | None | Shows the chat window |
| hide | None | Hides the chat window |
| event | "event_name" | Fires a specific event to track user interaction |
| attribute | "key", "value" | Updates or adds a new attribute for the user on the go |
| logout | None | Logs out the user from the live chat session |
| showArticle | "collectionSlugOrArticleId", "articleSlug" | Opens the chat window and displays an article |
| showBookMeeting | None | Opens the chat window and displays book meeting page |
| showNewMessage | "message" | Opens the chat window and displays a pre-populated message |
| sendNewMessage | "message" | Sends a new message from the user |
| registerCallback | CustomerlyCallback | Registers a callback function for various chat events |

$3

You can customize the appearance and behavior of the AI Chatbot by passing different information to the load function.

| Option | Type | Description | Required | Default |
| ------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------- |
| user_id | string | Unique identifier for the user | No | None |
| email | string | User's email address | No | None |
| name | string | User's full name | No | None |
| attributes | object | Customisable user details | No | None |
| company | object | Company details associated with the user | No | None |
| accentColor | string | HEX code to customize the main color of the live chat interface | No | None |
| contrastColor | string | HEX code to customize the contrast color of the live chat interface | No | None |
| position | object | Defines the position of the chat bubble on desktop and mobile (bottom and side offsets) | No | {desktop: {bottom: 0, side: 0}, mobile: {bottom: 0, side: 0}} |
| visible | boolean | Controls the visibility of the live chat on all devices | No | true |
| visibleOnMobile | boolean | Specifically controls the visibility of the live chat on mobile devices | No | true |
| attachmentsAvailable | boolean | Enables or disables the attachment feature in the chat interface | No | true |
| autodetectLocale | boolean | Allows or prevents the chat from automatically detecting and adapting to the user's locale | No | true |
| disableCSSOMInjection | boolean | Disables the styles injection which uses CSSStyleSheet JS API | No | false |

#### User authentication and custom attributes structure

`tsx
import React, {FunctionComponent, useEffect} from 'react';
import {CustomerlyProvider, useCustomerly} from 'react-live-chat-customerly';

const PROJECT_ID = 'YOUR_CUSTOMERLY_PROJECT_ID';

const App: FunctionComponent = () => (



);

const UserChatComponent: FunctionComponent = () => {
const {load} = useCustomerly();

// Effect to load the chat with user details when the component mounts
useEffect(() => {
load({
user_id: "123456", // Unique identifier for the user
name: "John Doe", // User's full name
email: "john.doe@example.com", // User's email address
attributes: { // Custom attributes for the user
signup_date: 1384902000, // Example attribute: user's signup date (Add dates as Unix timestamp)
plan_level: "premium", // Example attribute: user's subscription plan
age: 30 // Example attribute: user's age
}
});
}, []);

return (


);
};

export default App;
`

#### Company object structure

`tsx
import React, {FunctionComponent, useEffect} from 'react';
import {CustomerlyProvider, useCustomerly} from 'react-live-chat-customerly';

const PROJECT_ID = 'YOUR_CUSTOMERLY_PROJECT_ID';

const App: FunctionComponent = () => (



);

const ChatComponent: FunctionComponent = () => {
const {load} = useCustomerly();

// Load function with user and company details
useEffect(() => {
load({
user_id: "USER_ID", // Optionally pass user ID if available
email: "USER_EMAIL", // Replace with actual user email
name: "USER NAME", // Replace with actual user name
company: {
company_id: "COMPANY_ID",
name: "ACME",
address: "Ground Floor, 71 Lower Baggot Street",
city: "Dublin",
employees: 10,
admin_url: "https://www.company.com/admin/companyID",
sub_name: "Pro",
sub_period: "Yearly",
sub_state: "Active",
sub_amount: 1188,
last_payment_amount: 1188,
total_revenues: 5940,
domain: "company.com"
}
});
}, []);

return (


);
};

export default App;
`

$3

The update function is a critical tool within the Customerly Live Chat SDK, designed to refresh and sync user data and
configurations in real-time. This function is particularly useful in single-page applications (SPAs) where user contexts
and states can change without a full page reload.

To ensure that the user information displayed within the live chat remains accurate and current.
When to use:

- Typically, you should invoke the update function when significant user information changes, such as after editing a
profile, changing user settings, or upon user login/logout actions.
- Route changes: In SPAs, where route changes do not reload the entire application, it’s crucial to manually invoke the
update function to refresh the chat environment.

`tsx
import React, {FunctionComponent, useEffect, useContext} from 'react';
import {useCustomerly} from 'react-live-chat-customerly';
import {useLocation} from 'react-router-dom';

const UserProfilePage: FunctionComponent = () => {
const {update} = useCustomerly();
const location = useLocation();

const userDetails = {
email: 'john.doe@example.com',
name: 'John Doe',
attributes: {
membershipLevel: 'Gold',
}
};

useEffect(() => {
// Triggering the update function to refresh chat settings and surveys
update();
}, [location.pathname]); // Dependency on location.pathname to re-run on route changes

useEffect(() => {
update({
email: userDetails.email,
name: userDetails.name,
attributes: userDetails.attributes
});
}, [userDetails]); // Dependency on userDetails to re-run on user data changes

return (


);
};

export default UserProfilePage;
`

Callbacks

| Callback Function | Description | Returns |
|---------------------------------|-----------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| onLeadGenerated | Triggered when a new conversation is initiated, signaling a potential lead generation. | email (the lead's email if provided) |
| onChatOpened | Triggered when the chat window is opened by the client. | None |
| onChatClosed | Triggered when the chat window is closed by the client. | None |
| onNewConversation | Occurs when a new conversation is started by the client, useful for analytics tracking. | message, attachments |
| onProfilingQuestionAnswered | Triggered when a profiling question is answered, capturing the response details. | attribute, value |
| onProfilingQuestionAsked | Activated when a profiling question is presented to the visitor. | attribute (the related question asked) |
| onRealtimeVideoAnswered | Fired when a Realtime Video Call is answered by the client. | None |
| onRealtimeVideoRejected | Fired when a Realtime Video Call is rejected by the client. | None |
| onTriggerFired | Triggered when a chat trigger message is received by the customer. | triggerId (ID of the trigger fired) |
| onHelpCenterArticleOpened | Triggered when a client opens a Help Center Article within the live chat widget. | article (detailed attributes of the article) |
| onChatflowNotificationViewed | Triggered when a chatflow notification is viewed by the user. | notificationId, email |
| onChatflowNotificationClicked | Triggered when a chatflow notification is clicked by the user. | notificationId, item, email |
| onNewMessageReceived | Fired when a new message is received by the client. | message: { accountId, message, timestamp, userId, conversationId } |
| onNewConversationReceived | Triggered when a new conversation is received by the client. | conversationId |

`tsx
import React, {FunctionComponent, useEffect} from 'react';
import {CustomerlyProvider, useCustomerly} from 'react-live-chat-customerly';

const PROJECT_ID = 'YOUR_CUSTOMERLY_PROJECT_ID';

const App: FunctionComponent = () => (



);

const LeadGenChatComponent: FunctionComponent = () => {
const {registerCallback, load} = useCustomerly();

useEffect(() => {
load();

// Define the callback function for a new lead generation
const onLeadGenerated = (email: string) => {
// Here you can add the logic to handle the new lead, such as
// sending the data to your analytics tool
};

// Register the callback
registerCallback({
type: 'onLeadGenerated',
function: onLeadGenerated
});
}, []);

// Render UI here
return

;
};

export default App;
`

Example playground

This is a basic playground to try the Customerly messenger features and custom implementation.

`tsx
import React, {FunctionComponent} from 'react';
import {CustomerlyProvider, useCustomerly} from 'react-live-chat-customerly';

const PROJECT_ID = 'YOUR_CUSTOMERLY_PROJECT_ID';

const TestChatFunctionsPage: FunctionComponent = () => {
const {
load,
update,
open,
close,
show,
hide,
event,
attribute,
logout,
showNewMessage,
sendNewMessage,
registerCallback
} = useCustomerly();

useEffect(() => {
load({
user_id: "test_user_id",
email: "test@example.com",
name: "Test User",
attributes: {
role: "tester"
},
company: {
company_id: "test_company_id",
name: "Test Company"
}
});

// Define the callback function for a new conversation started
const onNewConversation = (message: string) => {
console.log('New conversation started:', message);
};

// Register the callback
registerCallback({
type: 'onNewConversation',
function: onNewConversation
});
}, []);


const testUpdate = () => {
update({
user_id: "test_user_id",
email: "test@example.com",
name: "Test User Updated",
attributes: {
role: "tester",
plan: "Enterprise",
},
company: {
company_id: "test_company_id",
name: "Test Company"
}
});
};


return (


);
};

const App: FunctionComponent = () => (



);

export default App;
``

Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements,
please create an issue or submit a pull request.