Skip to content

Chat Widget

The ConnectyCube Web Chat Widget is designed to simplify the process of adding chat functionality to your Web apps. This widget offers an out-of-the-box solution for embedding chat features - such as instant messaging, user presence, and file sharing - without the overhead of building a complete chat system from scratch. Key benefits include:

  • Easy integration: plug the widget into your existing Web projects.
  • Customizable interface: adjust the look and feel to match your brand.
  • Real-time messaging: leverage ConnectyCube’s reliable backend for instant communication.
  • Responsive design: works seamlessly on both desktop and mobile devices.
  • Modular and extensible: adapt the widget to your unique requirements.

Demo

https://connectycube-chat-widget.onrender.com

Split-view mode

ConnectyCube chat widget, split view image demo

Single-view mode

ConnectyCube chat widget, single view image demo

Code samples

See chat widget code samples as a reference for faster integration.

Installation

Terminal window
npm install @connectycube/chat-widget
// or
yarn add @connectycube/chat-widget

Display widget

Before you start

Before you start, make sure:

  1. You have access to your ConnectyCube account. If you don’t have an account, sign up here.
  2. An app created in ConnectyCube dashboard. Once logged into your ConnectyCube account, create a new application and make a note of the app credentials (App ID and Auth Key) that you’ll need for authentication.

React

Import and place the following component in your app:

import ConnectyCubeChatWidget from "@connectycube/chat-widget";
...
<ConnectyCubeChatWidget
appId="123"
authKey="11111111-2222-3333-4444-55555555"
userId="45"
userName="Samuel"
showOnlineUsersTab={false}
splitView={true}
/>
// userName - how other users will see your user name
// userId - a User Id from your system

See chat widget code samples as a reference for faster integration.

React 19

By default, the widget uses the React 18-compatible build. To use it with React 19, import the dedicated ESM-only build instead:

import ConnectyCubeChatWidget from '@connectycube/chat-widget/react19';

Vanilla JS

Place the following script in your app:

<!doctype html>
<html lang="en">
<head>
<!-- ... -->
</head>
<body>
<!-- ... -->
<!-- @connectycube/chat-widget - start -->
<script src="https://unpkg.com/react@18/umd/react.production.min.js" crossorigin></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js" crossorigin></script>
<script src="https://unpkg.com/connectycube@4/dist/connectycube.min.js"></script>
<script src="https://unpkg.com/@connectycube/chat-widget@latest/dist/index.umd.js"></script>
<script>
const chatWidgetContainer = document.createElement('div');
chatWidgetContainer.id = 'ConnectyCube_chat-widget';
document.body.appendChild(chatWidgetContainer);
const props = {
appId: 123,
authKey: '11111111-2222-3333-4444-55555555',
userId: '45', // a User Id from your system
userName: 'Samuel', // how other users will see your user name
showOnlineUsersTab: false,
splitView: true,
};
ReactDOM.createRoot(chatWidgetContainer).render(React.createElement(ConnectyCubeChatWidget, props));
</script>
<!-- @connectycube/chat-widget - end -->
</body>
</html>

See chat widget code samples as a reference for faster integration.

Feature configuration

This section explains how to control specific features of the chat widget by enabling or disabling them through configuration props. Customize your widget behavior to meet your specific requirements without having to modify the core code.

Notifications

This section allows you to configure how users are notified about new messages. You can control notifications, browser push notifications, and notification sounds independently for a fully customizable experience:

  • showNotifications - show browser notifications about new messages received
  • webPushNotifications - show browser push notifications about new messages received
  • playSound - play sound about new messages received

Online users

showOnlineUsersTab - displays a dedicated tab within the chat widget that lists all currently online users. This feature is useful in team or community-based chat environments where it’s helpful to see who’s available before starting a conversation.

Toggle Button visibility

hideWidgetButton - controls the visibility of the floating button that users click to open or close the chat widget. This is useful when you want to launch the widget programmatically or embed it inside a custom UI element instead of showing the default button. Read how to open a widget by clicking on custom button

New chat buttons

These settings let you control whether users can start new chats or initiate one-on-one conversations. Use them to restrict chat creation in specific environments or use cases, such as read-only communities or customer support-only contexts.

  • hideNewChatButton - controls the visibility of the main “New Chat” button in the chat widget interface.
  • hideNewUserChatOption - hides the option to start a new 1-on-1 conversation from within the “Create Chat” flow. This is useful when you only want to allow group chats or predefined channels.

Moderation

The moderation settings help maintain a safe and respectful chat environment. These options allow users to report inappropriate content and manage their personal block lists, giving them more control over their experience.

At then moment the following moderation features supported:

  • enableContentReporting - users can report messages via a UI action
  • enableBlockList - users can block and unblock others from their profile

Report user

To enable Report user feature, you need to pass enableContentReporting: true prop. This will display a Report button in user profile:

Chat widget: report user button

For user reporting to work properly, it requires the following:

  1. Go to ConnectyCube Daashboard
  2. select your Application
  3. Navigate to Custom module via left sidebar
  4. Create new table called UserReports with the following fields:
  • reportedUserId - integer
  • reason - string
Chat widget: report table in ConnectyCube dashboard

Once the table is created, you can test the user reporting in Widget. You will see the reports appear in this table.

Block user

To enable Block user feature, you need to pass enableBlockList: true prop. This will display a Block button in user profile (see above).

Appearance & Styling

The Appearance & Styling settings let you fully customize the visual presentation of the chat widget. You can control the look of the toggle button, badge, and chat portal using inline styles or CSS class names. This ensures your widget blends seamlessly into your app or site design.

Chat toggle button

  • buttonTitle - sets the accessible title (title attribute) of the chat toggle button. This is typically used for accessibility or tooltip text when hovering over the button
  • buttonStyle - applies inline styles to the chat toggle button

Portal

  • portalStyle - applies inline styles to the main chat window (portal)

Badge

  • badgeStyle - applies inline styles to the notification badge that appears on the toggle button (e.g., unread messages count)

Props

Prop NameTypeDescriptionDefault Value
appIdnumber | stringThe ConnectyCube Application ID
authKeystringThe ConnectyCube Authentication Key
configobject(Optional) Configuration options for ConnectyCube SDK
userIdstringA User Id from your system
userNamestringUser name. This is how other users will see your user name
userAvatarstring(Optional) User Avatar URL
userProfileLinkstring(Optional) User profile link URL
translationstring(Optional) Specifies the language for the chat widget. See Supported Translations”en”
disableClickOutsideboolean(Optional) Hide chat widget by click or touch, or press “Escape” outside widget’s containersfalse
hideWidgetButtonboolean(Optional) Allows to hide the button that opens/hides the chat widgetfalse
buttonTitlestring(Optional) The text displayed on the chat button”Chat”
portalStyleReact.CSSProperties(Optional) Inline styles for the portal
buttonStyleReact.CSSProperties(Optional) Inline styles for the button
badgeStyleReact.CSSProperties(Optional) Inline styles for the unread messages badge
onlineBadgeStyleReact.CSSProperties(Optional) Inline styles for the online users count badge
openboolean(Optional) To control the visibility state of the chat widgetfalse
embedViewboolean(Optional) Embeds chat view by filling parent block. Props open and hideNewChatButton won’t react and will be true by defaultfalse
splitViewboolean(Optional) Displays the chats in split view or single viewfalse
showChatStatusboolean(Optional) Displays the chat connection status indicatorfalse
showOnlineUsersTabboolean(Optional) Displays users tab with the list of online usersfalse
hideNewChatButtonboolean(Optional) Allows to hide the chat creation buttonfalse
hideNewUserChatOptionboolean(Optional) Allows to hide the New Message option in New Chat dropdownfalse
hideNewGroupChatOptionboolean(Optional) Allows to hide the New Group option in New Chat dropdownfalse
mutedboolean(Optional) Mutes or unmutes notifications and soundsfalse
showNotificationsboolean(Optional) Allows receiving browser notificationsfalse
playSoundboolean(Optional) Enables or disables playing sound on incoming messagestrue
webPushNotificationsboolean(Optional) Allows receiving browser push notificationsfalse
webPushVapidPublicKeystring(Optional) Vapid Public Key for push notificationsfalse
serviceWorkerPathstring(Optional) Path to service worker for push notificationsfalse
attachmentsAcceptstring(Optional) This prop sets to the accept attribute in HTML /
enableUserStatusesboolean(Optional) Enable user statuses, such as “Available”, “Busy” and “Away”false
enableLastSeenboolean(Optional) Displays green dot on user avatar in chats list when user is online and last seen information on chat headerfalse
enableContentReportingboolean(Optional) Enable reporting bad content feature (will show Report button in user profile)false
enableBlockListboolean(Optional) Enable block user feature (will show Block button in user profile)false
enableOnlineUsersBadgeboolean(Optional) Displays online users badge on chat widget buttonfalse
getOnlineUsersIntervalnumber(Optional) Allows to set how frequently the badge should be updated, in seconds. Min is 30 seconds300
enableUrlPreviewboolean(Optional) Allows to unfurl a link once posted in chatfalse
limitUrlsPreviewsnumber(Optional) Allows to set maximum displayed URLs preview in single message. Max is 51
quickActionsobject(Optional) Configuration for quick actions dialog. See QuickActions
defaultChatobject(Optional) Force widget to open particular chat
onUnreadCountChange(count: boolean) => void(Optional) Callback function to get update about unread messages count
onOnlineUsersCountChange(count: boolean) => void(Optional) Callback function to get update about online users count
onOpenChange(open: boolean) => void(Optional) Callback function to get update about chat widget visibility

Quick Actions

Prop NameTypeDescriptionDefault Value
titlestring(Optional) Title for the quick actions section
descriptionstring(Optional) Description for the quick actions
actionsstring[]List of action strings
ConnectyCube chat widget, Quick Actions demo

Supported Translations

Language CodeLanguage
enEnglish
elGreek
uaUkrainian

Default Chat

Prop NameTypeDescriptionDefault Value
idstringA key that will be used to identify the chat
opponentUserIdstringUser id to create chat with. Must be a User Id from your system, similar to userId prop
typestringType of chat to create if not exist: 1on1 or group
namestringName of new chat
metadatamapNew chat metadata

Push notifications

Push notifications allow to receive a message while the browser tab with widget is closed.

For push notifications to work it need to do the following:

  1. pass webPushNotifications: true prop
  2. go to ConnectyCube Dashboard, Push Notifications, Credentials, WEBPUSH NOTIFICATIONS and fill all the required fields (Subject, PublicKey, PrivateKey)
  3. for webPushVapidPublicKey prop to set the same PublicKey which you set in ConnectyCube Dashboard.
  4. create a service worker and provide path to it via serviceWorkerPath prop. See chat widget code samples as a reference.

Recipes

Split view

<ConnectyCubeChatWidget
...
splitView={true}
/>

Single view

<ConnectyCubeChatWidget
...
splitView={false}
/>

Embedded view

const myStyles = {
position: 'relative',
display: 'flex',
right: '0',
top: '0',
minWidth: '100%',
minHeight: '100%',
zIndex: '0',
};
<ConnectyCubeChatWidget
...
portalStyle={myStyles}
/>

Display Chat button bottom left

<ConnectyCubeChatWidget
...
buttonStyle={{"left": "0.5rem", "right": "auto"}}
portalStyle={{"left": "0.5rem", "right": "auto"}}
/>

Open widget on custom button

<ConnectyCubeChatWidget
...
open={true}
/>

Have an issue?

Join our Discord for quick answers to your questions

Changelog

https://github.com/ConnectyCube/connectycube-chat-widget-samples/blob/main/CHANGELOG.md