@ethora/chat-component 25.6.3 → 25.6.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +392 -99
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -7,13 +7,15 @@
|
|
|
7
7
|
|
|
8
8
|
[](https://discord.gg/Sm6bAHA3ZC) [](https://twitter.com/intent/tweet?url=https%3A%2F%2Fgithub.com%2Fdappros%2Fethora%2F&via=tarasfilatov&text=check%20out%20Ethora%20%23web3%20%23social%20app%20engine&hashtags=lowcode%2Creactnative%2Copensource%2Cnocode) [](https://ethora.com/) [](https://www.youtube.com/channel/UCRvrXwMOU0WBkRZyFlU7V_g)
|
|
9
9
|
|
|
10
|
+
[](https://codesandbox.io/s/ethora-chat-component-demo)
|
|
11
|
+
|
|
10
12
|
## About Chat Component
|
|
11
13
|
|
|
12
14
|
Ethora Chat Component allows you to build a functioning chat room super quickly.
|
|
13
15
|
Sounds simple and is easy to build your app with.
|
|
14
16
|
Uses XMPP chat protocol and ejabberd chat server to provide your users with a seamless instant messaging experience.
|
|
15
17
|
|
|
16
|
-
Once you need more functionality however you will be pleasantly surprised. Our Ethora platform behind the chat component offers a plethora of functionalities around chat/social, user profiles, digital wallets, business documents exchange, digital collectables, web3 and AI bots. The history behind Chat Component is following. First, we have built a low-code
|
|
18
|
+
Once you need more functionality however you will be pleasantly surprised. Our Ethora platform behind the chat component offers a plethora of functionalities around chat/social, user profiles, digital wallets, business documents exchange, digital collectables, web3 and AI bots. The history behind Chat Component is following. First, we have built a low-code "super app" engine called Ethora: https://github.com/dappros/ethora/ which we used to drastically speed up app development for our clients. Afterwards, we have open-sourced it for the benefit of other developers. Later on, we realized that whilst developers love what Ethora can do, many of them don't need such a complex engine with all bells and whistles but a steep learning curver. In most cases you're after a certain functionality (like a simple chat room) and you need it quick.
|
|
17
19
|
|
|
18
20
|
Enter Ethora Chat Component which allows you to quickly implement your chat room experience!
|
|
19
21
|
|
|
@@ -21,48 +23,121 @@ If / once you need additional functionalities you will have options like: (a) bu
|
|
|
21
23
|
|
|
22
24
|
Note: scroll below for use cases and functionality break down of this Chat Component.
|
|
23
25
|
|
|
24
|
-
##
|
|
26
|
+
## Proven in Real Projects & Customization Support
|
|
25
27
|
|
|
26
|
-
|
|
27
|
-
2. specify a name for your project (e.g. "vite-project")
|
|
28
|
-
3. select framework and variant (for example, React -> Typescript but may be different depending on your project requirements, it will work with plain Javascript too)
|
|
28
|
+
Ethora Chat Component is a production-ready solution, successfully used in more than 5 different commercial and open-source projects across various industries. Our team has deep experience integrating and customizing this component for a wide range of use cases—from social apps and enterprise messengers to support bots and community platforms.
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
**Need custom features or integration help?**
|
|
31
|
+
We can help you tailor the chat experience to your needs—UI/UX, authentication, integrations, bots, and more. Just [contact us](https://www.ethora.com/#contact) or join our [community forum](https://forum.ethora.com/) to discuss your requirements!
|
|
31
32
|
|
|
32
|
-
|
|
33
|
+
## Integration & Technical Requirements
|
|
33
34
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
6. npm i @ethora/chat-component
|
|
37
|
-
7. go to file src/App.tsx and replace it with the below code
|
|
35
|
+
- **XMPP Provider Required:**
|
|
36
|
+
The chat component must be wrapped in an `XmppProvider` for initialization and context. This is essential for all XMPP operations.
|
|
38
37
|
|
|
39
|
-
|
|
40
|
-
import { Chat } from "@ethora/chat-component";
|
|
41
|
-
import "./App.css";
|
|
38
|
+
**Best Practice:**
|
|
42
39
|
|
|
43
|
-
|
|
44
|
-
return (
|
|
45
|
-
<Chat />
|
|
46
|
-
);
|
|
47
|
-
}
|
|
40
|
+
> You can (and should) wrap your entire app with `XmppProvider` if you use chat features in multiple places. This ensures your app will utilize only one XMPP WebSocket connection, improving efficiency and resource usage.
|
|
48
41
|
|
|
49
|
-
|
|
50
|
-
```
|
|
42
|
+
**Example: Wrapping your whole app**
|
|
51
43
|
|
|
52
|
-
|
|
44
|
+
```tsx
|
|
45
|
+
import { XmppProvider } from '@ethora/chat-component';
|
|
46
|
+
import App from './App';
|
|
53
47
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
48
|
+
const config = {
|
|
49
|
+
/* ...see config table below... */
|
|
50
|
+
};
|
|
57
51
|
|
|
58
|
-
|
|
59
|
-
|
|
52
|
+
export default function Root() {
|
|
53
|
+
return (
|
|
54
|
+
<XmppProvider config={config}>
|
|
55
|
+
<App />
|
|
56
|
+
</XmppProvider>
|
|
57
|
+
);
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
60
|
|
|
61
|
-
|
|
61
|
+
**Example: Wrapping just the chat**
|
|
62
62
|
|
|
63
|
-
|
|
63
|
+
```tsx
|
|
64
|
+
<XmppProvider config={config}>
|
|
65
|
+
<Chat ...props />
|
|
66
|
+
</XmppProvider>
|
|
67
|
+
```
|
|
68
|
+
- If you wrap your whole app, all chat-related components will share the same XMPP connection and context.
|
|
69
|
+
- If you only use chat in one place, you can wrap just the chat component.
|
|
64
70
|
|
|
65
|
-
|
|
71
|
+
- **Redux Store:**
|
|
72
|
+
The component expects a Redux store with specific slices (`rooms`, `chatSettingStore`). If you use your own store, ensure compatibility or adapt the slices.
|
|
73
|
+
- **User Object Structure:**
|
|
74
|
+
The user object (for login, config, etc.) must include fields like `xmppUsername`, `xmppPassword`, and optionally `defaultWallet`.
|
|
75
|
+
- **Room Object Structure:**
|
|
76
|
+
Room objects must follow the `IRoom` interface, including `jid`, `name`, `members`, etc.
|
|
77
|
+
- **Logout Handling:**
|
|
78
|
+
The component listens for a custom event (`ethora-xmpp-logout`) to disconnect the XMPP client. If you implement custom logout logic, dispatch this event to ensure proper cleanup.
|
|
79
|
+
- **Custom Message Rendering:**
|
|
80
|
+
You can provide a custom message component via the `CustomMessageComponent` prop for full control over message bubble rendering.
|
|
81
|
+
- **Translations:**
|
|
82
|
+
The `translates` config enables message translation and localization, supporting multiple languages.
|
|
83
|
+
|
|
84
|
+
## How to build your chat room in 5 minutes
|
|
85
|
+
|
|
86
|
+
1. Create a new Vite React project:
|
|
87
|
+
```bash
|
|
88
|
+
npm create vite@latest
|
|
89
|
+
# Follow prompts (choose React + TypeScript or JavaScript)
|
|
90
|
+
cd your-project-name
|
|
91
|
+
npm install
|
|
92
|
+
```
|
|
93
|
+
2. Install the Ethora chat component:
|
|
94
|
+
```bash
|
|
95
|
+
npm install @ethora/chat-component
|
|
96
|
+
```
|
|
97
|
+
3. Add your Ethora/Firebase config (for Google SSO) or use default login for quick start.
|
|
98
|
+
4. Replace your `src/App.tsx` with the following minimal example:
|
|
99
|
+
|
|
100
|
+
```tsx
|
|
101
|
+
import { XmppProvider, Chat } from '@ethora/chat-component';
|
|
102
|
+
import './App.css';
|
|
103
|
+
|
|
104
|
+
// Minimal config for demo/testing (see README for full options)
|
|
105
|
+
const config = {
|
|
106
|
+
defaultLogin: true, // For demo/testing, disables login screen
|
|
107
|
+
colors: { primary: '#4287f5', secondary: '#42f5e9' },
|
|
108
|
+
// For production, use googleLogin, jwtLogin, or userLogin
|
|
109
|
+
// googleLogin: { enabled: true, firebaseConfig: { ... } },
|
|
110
|
+
};
|
|
111
|
+
|
|
112
|
+
function App() {
|
|
113
|
+
return (
|
|
114
|
+
<XmppProvider config={config}>
|
|
115
|
+
<Chat
|
|
116
|
+
MainComponentStyles={{
|
|
117
|
+
width: '100%',
|
|
118
|
+
height: '500px',
|
|
119
|
+
borderRadius: '16px',
|
|
120
|
+
}}
|
|
121
|
+
// Optionally: CustomMessageComponent={MyCustomMessage}
|
|
122
|
+
/>
|
|
123
|
+
</XmppProvider>
|
|
124
|
+
);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
export default App;
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
5. Start your app:
|
|
131
|
+
```bash
|
|
132
|
+
npm run dev
|
|
133
|
+
```
|
|
134
|
+
6. Open http://localhost:5173/ in your browser. You should see your chat app running!
|
|
135
|
+
|
|
136
|
+
**Tip:**
|
|
137
|
+
|
|
138
|
+
- For production, configure authentication (Google SSO, JWT, or user login) and pass your real config object.
|
|
139
|
+
- You can wrap your entire app with `XmppProvider` to share a single XMPP connection across all chat features.
|
|
140
|
+
- For advanced options and custom UI, see the configuration and styling sections below.
|
|
66
141
|
|
|
67
142
|
ℹ️ Note: your Ethora App, User and Chat credentials are hard-coded and login screen is bypassed. This is done so that you can scaffold and test the functionality quickly.
|
|
68
143
|
Leave this as is if you only need to demo or validate the chat functionality as part of your project.
|
|
@@ -70,79 +145,102 @@ If you need to have your own private chats, be able to login multiple users etc
|
|
|
70
145
|
|
|
71
146
|
## Extra options (styling etc)
|
|
72
147
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
148
|
+
You can customize the chat component extensively using the `config` prop and other options. Here are some of the most useful and advanced configuration options:
|
|
149
|
+
|
|
150
|
+
- **Styling**
|
|
151
|
+
- `colors`: Set primary and secondary theme colors.
|
|
152
|
+
- `roomListStyles`: Custom styles for the room list (left panel).
|
|
153
|
+
- `chatRoomStyles`: Custom styles for the chat area (right panel).
|
|
154
|
+
- `backgroundChat`: Set a background color or image for the chat area.
|
|
155
|
+
- `headerLogo`: Add a custom logo to the chat header.
|
|
156
|
+
- `chatHeaderAdditional`: Add a custom element to the chat header.
|
|
157
|
+
|
|
158
|
+
- **Room and Navigation**
|
|
159
|
+
- `disableHeader`: Hide the chat header.
|
|
160
|
+
- `disableRooms`: Show only a single room (no room list).
|
|
161
|
+
- `forceSetRoom`: Always show a specific room.
|
|
162
|
+
- `setRoomJidInPath`: Reflect the room JID in the URL for deep linking.
|
|
163
|
+
- `defaultRooms`: Provide a list of default rooms.
|
|
164
|
+
- `disableNewChatButton`: Hide the new chat button.
|
|
165
|
+
|
|
166
|
+
- **Login and Authentication**
|
|
167
|
+
- `googleLogin`, `jwtLogin`, `userLogin`, `customLogin`: Multiple authentication strategies supported.
|
|
168
|
+
- `defaultLogin`: Use a default demo/test login.
|
|
169
|
+
|
|
170
|
+
- **Message and Input**
|
|
171
|
+
- `disableMedia`: Disable file/image/audio attachments.
|
|
172
|
+
- `secondarySendButton`: Add a secondary send button (e.g., for message editing or custom actions).
|
|
173
|
+
- `messageTextFilter`: Filter or transform message text before sending.
|
|
174
|
+
|
|
175
|
+
- **Localization and Translation**
|
|
176
|
+
- `translates`: Enable message translation and localization.
|
|
177
|
+
|
|
178
|
+
- **Advanced**
|
|
179
|
+
- `enableRoomsRetry`: Enable retry logic and custom helper text if no rooms are available.
|
|
180
|
+
- `botMessageAutoScroll`: Enable auto-scroll for bot messages.
|
|
181
|
+
- `initBeforeLoad`: Initialize XMPP before loading the UI.
|
|
182
|
+
- `refreshTokens`: Enable token refresh logic.
|
|
183
|
+
|
|
184
|
+
### Example: Customizing the Chat Component
|
|
185
|
+
|
|
186
|
+
```tsx
|
|
187
|
+
import { XmppProvider, Chat } from '@ethora/chat-component';
|
|
188
|
+
|
|
189
|
+
const config = {
|
|
190
|
+
colors: { primary: '#4287f5', secondary: '#42f5e9' },
|
|
191
|
+
disableHeader: false,
|
|
192
|
+
disableMedia: false,
|
|
193
|
+
roomListStyles: { width: '300px', background: '#f5f5f5' },
|
|
194
|
+
chatRoomStyles: { borderRadius: '16px', border: '1px solid #42f5e9' },
|
|
195
|
+
backgroundChat: { color: '#f0f0f0' },
|
|
196
|
+
headerLogo: '/logo.png',
|
|
197
|
+
chatHeaderAdditional: { enabled: true, element: <MyCustomHeaderElement /> },
|
|
198
|
+
forceSetRoom: false,
|
|
199
|
+
setRoomJidInPath: true,
|
|
200
|
+
disableNewChatButton: false,
|
|
201
|
+
googleLogin: {
|
|
202
|
+
enabled: true,
|
|
203
|
+
firebaseConfig: {
|
|
204
|
+
/* ...firebase config... */
|
|
93
205
|
},
|
|
94
|
-
|
|
206
|
+
},
|
|
207
|
+
secondarySendButton: {
|
|
208
|
+
enabled: true,
|
|
209
|
+
messageEdit: ' (edited)',
|
|
210
|
+
label: 'Edit',
|
|
211
|
+
buttonStyles: { background: '#42f5e9', color: '#fff' },
|
|
212
|
+
hideInputSendButton: false,
|
|
213
|
+
overwriteEnterClick: true,
|
|
214
|
+
},
|
|
215
|
+
translates: { enabled: true },
|
|
216
|
+
enableRoomsRetry: {
|
|
217
|
+
enabled: true,
|
|
218
|
+
helperText: 'No rooms found, please try again.',
|
|
219
|
+
},
|
|
220
|
+
botMessageAutoScroll: true,
|
|
221
|
+
messageTextFilter: {
|
|
222
|
+
enabled: true,
|
|
223
|
+
filterFunction: (text) => text.replace(/badword/gi, '***'),
|
|
224
|
+
},
|
|
225
|
+
};
|
|
226
|
+
|
|
227
|
+
<XmppProvider config={config}>
|
|
228
|
+
<Chat
|
|
95
229
|
MainComponentStyles={{
|
|
96
|
-
width:
|
|
97
|
-
height:
|
|
98
|
-
borderRadius:
|
|
99
|
-
border: "1px solid #42f5e9",
|
|
230
|
+
width: '100%',
|
|
231
|
+
height: '600px',
|
|
232
|
+
borderRadius: '16px',
|
|
100
233
|
}}
|
|
101
234
|
roomJID=""
|
|
102
|
-
user={{ email:
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
disableRooms: boolean;
|
|
106
|
-
defaultLogin: boolean;
|
|
107
|
-
disableInteractions: boolean; //disable interactions
|
|
108
|
-
chatHeaderBurgerMenu: boolean; // disable burger menu in room header
|
|
109
|
-
roomListStyles: React.CSSProperties; // used to change room List styles (left)
|
|
110
|
-
chatRoomStyles: React.CSSProperties; // used to change room styles (right)
|
|
111
|
-
setRoomJidInPath: boolean; // used to set RoomId to url
|
|
235
|
+
user={{ email: '', password: '' }}
|
|
236
|
+
CustomMessageComponent={MyCustomMessage}
|
|
112
237
|
/>
|
|
238
|
+
</XmppProvider>;
|
|
113
239
|
```
|
|
114
240
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
ℹ️ Note:
|
|
118
|
-
There is also a prop CustomMessageComponent: React.ComponentType<MessageProps>
|
|
119
|
-
This prop is used to fully change styles of messageBubble.
|
|
120
|
-
You can find an example here: https://github.com/dappros/ethora-chat-component/blob/main/src/components/ExampleComponents/CustomMessage.tsx
|
|
121
|
-
|
|
122
|
-
For styling you can alter **App.css**:
|
|
123
|
-
|
|
124
|
-
```
|
|
125
|
-
#root {
|
|
126
|
-
width: 100%;
|
|
127
|
-
margin: 0 auto;
|
|
128
|
-
text-align: center;
|
|
129
|
-
}
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
and **index.css**:
|
|
241
|
+
- You can also provide a custom message component via the `CustomMessageComponent` prop to fully control the rendering of message bubbles. See [`src/components/ExampleComponents/CustomMessage.tsx`](https://github.com/dappros/ethora-chat-component/blob/main/src/components/ExampleComponents/CustomMessage.tsx) for an example.
|
|
133
242
|
|
|
134
|
-
|
|
135
|
-
body {
|
|
136
|
-
margin: 0;
|
|
137
|
-
display: flex;
|
|
138
|
-
place-items: center;
|
|
139
|
-
min-width: 320px;
|
|
140
|
-
min-height: 100vh;
|
|
141
|
-
width: 100%;
|
|
142
|
-
}
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
After these changes you can modify **MainComponentStyles** for your chat.
|
|
243
|
+
- For styling, you can further alter **App.css** and **index.css** as needed.
|
|
146
244
|
|
|
147
245
|
## Architecture Diagram
|
|
148
246
|
|
|
@@ -175,10 +273,10 @@ Supported by Ethora platform but not implemented into Chat Component yet:
|
|
|
175
273
|
- Use Case 1: **One global chat room for all users** ✅ - (e.g. chat lobby for all of your website / app users). Simply create a chat room manually and hardcode the UUID into your chat component code.
|
|
176
274
|
- Use Case 2: **One chat room per case** ✅ - (e.g. customer support session, AI bot, a chat room for each location or department, web page specific chat etc). You have to create rooms as required by your business logic via Ethora API and then pass the corresponding chat UUID into chat component. Your end User will see the corresponding room.
|
|
177
275
|
|
|
178
|
-
#### "Multiple rooms - messenger / social app
|
|
276
|
+
#### "Multiple rooms - messenger / social app"
|
|
179
277
|
|
|
180
278
|
- Use Case 3: **Users can switch between Chats** ✅
|
|
181
|
-
Similar to Use Case 2, but also allows your User to switch to the **List of Chats** where they can see chat rooms, the count of new messages and a last message for
|
|
279
|
+
Similar to Use Case 2, but also allows your User to switch to the **List of Chats** where they can see chat rooms, the count of new messages and a last message for each room etc. Users can create new Chats and invite others into Chats (depending on your App settings). This functionality is now available in the Chat Component.
|
|
182
280
|
|
|
183
281
|
#### Misc core chat functionalities
|
|
184
282
|
|
|
@@ -187,16 +285,23 @@ Supported by Ethora platform but not implemented into Chat Component yet:
|
|
|
187
285
|
- **Chat history caching and scrolling** ✅
|
|
188
286
|
- **Chat history date divider** ✅
|
|
189
287
|
- **Now typing** ✅ - when someone is typing, other room Users will see indication of who is typing
|
|
288
|
+
- **Threaded replies** ✅ - Users can reply to messages in threads and view full message threads
|
|
289
|
+
- **Message translation/multi-language support** ✅ - Built-in support for message translation and language selection
|
|
290
|
+
- **Custom message component support** ✅ - Developers can provide a custom React component to fully control the rendering of message bubbles
|
|
190
291
|
|
|
191
292
|
#### Message interactions
|
|
192
293
|
|
|
193
294
|
- **Message menu** ✅ - Long tap or right click opens message menu with "Reply", "Copy", "Edit", "Delete", "Report" options available as well as send Coin / Item options
|
|
194
295
|
- **Emoji Reactions** ✅ - Users are able to long tap / click on the message and send Emoji reactions to the message. Reactions are displayed in the corner of the message bubble.
|
|
296
|
+
- **Reply to message (threaded replies)** ✅
|
|
297
|
+
- **Edit message** ✅
|
|
298
|
+
- **Delete message** ✅
|
|
299
|
+
- **Copy message** ✅
|
|
195
300
|
|
|
196
301
|
#### Avatars (profile photos)
|
|
197
302
|
|
|
198
303
|
- **Basic avatars** ✅ - in chat screen, users can see basic avatars next to chat bubbles. Simply default avatar icon for everyone.
|
|
199
|
-
- **"Initials" avatars** ✅ - in Chat
|
|
304
|
+
- **"Initials" avatars** ✅ - in Chat screen, users who don't have photos uploaded will show as "initials" avatars generated by taking the first letter of User's first name and last name
|
|
200
305
|
- **Google SSO avatars** 🚧 <sub><sup>(available in [Ethora git repo](https://github.com/dappros/ethora))</sup></sub> - when using Google SSO, their Google profile photo will be automatically displayed as chat avatar
|
|
201
306
|
- **Custom profile photos** ✅ - users are able to upload their custom photos when managing their Profile and the mini-photo will be displayed as a chat avatar
|
|
202
307
|
|
|
@@ -206,7 +311,10 @@ Supported by Ethora platform but not implemented into Chat Component yet:
|
|
|
206
311
|
|
|
207
312
|
### FILE ATTACHMENTS
|
|
208
313
|
|
|
209
|
-
- **File attachments** ✅ - file attachments, previews, media attachments, audio/video player etc
|
|
314
|
+
- **File attachments** ✅ - file attachments, previews, media attachments, audio/video player etc are implemented in the chat component
|
|
315
|
+
- **Image upload and preview** ✅
|
|
316
|
+
- **Video upload and playback** ✅
|
|
317
|
+
- **Audio message recording and playback** ✅
|
|
210
318
|
|
|
211
319
|
### USER PROFILES AND DIGITAL WALLET FUNCTIONALITY
|
|
212
320
|
|
|
@@ -217,6 +325,72 @@ Supported by Ethora platform but not implemented into Chat Component yet:
|
|
|
217
325
|
- **Profile Asset: Media (audio, video) files** 🚧 <sub><sup>(available in [Ethora git repo](https://github.com/dappros/ethora))</sup></sub> - Media files playable right from Profiles.
|
|
218
326
|
- **Profile Asset: Digital Art (collectables / NFT)** 🚧 <sub><sup>(available in [Ethora git repo](https://github.com/dappros/ethora))</sup></sub> - For projects which support rewarding Users with unique digital collectables and/or allowing Users to upload/mint, distribute or trade digital art or collectables.
|
|
219
327
|
|
|
328
|
+
### ADDITIONAL FUNCTIONALITY
|
|
329
|
+
|
|
330
|
+
- **Room member management (add/remove users)** ✅ - Users can add or remove members from group chats
|
|
331
|
+
- **Room creation modal with image upload** ✅ - Users can create new rooms and upload a room image
|
|
332
|
+
- **JWT Login** ✅ - Supports JWT-based login via the `jwtLogin` config.
|
|
333
|
+
- **Custom Login** ✅ - Supports a fully custom login function via the `customLogin` config.
|
|
334
|
+
- **Room List and Chat Room Styling** ✅ - Style the room list and chat area with `roomListStyles` and `chatRoomStyles`.
|
|
335
|
+
- **Force Set Room** ✅ - The `forceSetRoom` config can force the component to always show a specific room.
|
|
336
|
+
- **Room List in URL** ✅ - The `setRoomJidInPath` config allows the room JID to be reflected in the URL.
|
|
337
|
+
- **Secondary Send Button** ✅ - The `secondarySendButton` config allows for a secondary send action (e.g., for message editing).
|
|
338
|
+
- **Room Retry Logic** ✅ - The `enableRoomsRetry` config enables retry logic and custom helper text if no rooms are available.
|
|
339
|
+
- **Background Customization** ✅ - The `backgroundChat` config allows setting a background color or image for the chat.
|
|
340
|
+
- **Translation/Localization** ✅ - The `translates` config enables message translation and localization.
|
|
341
|
+
- **Room Creation Control** ✅ - The `disableNewChatButton` config disables the new chat button.
|
|
342
|
+
- **Bot Message Auto Scroll** ✅ - The `botMessageAutoScroll` config enables auto-scrolling for bot messages.
|
|
343
|
+
- **Message Text Filter** ✅ - The `messageTextFilter` config allows filtering or transforming message text before sending.
|
|
344
|
+
|
|
345
|
+
## Configuration Reference
|
|
346
|
+
|
|
347
|
+
Below is a table describing each property of the `IConfig` model (from `src/types/models/config.model.ts`):
|
|
348
|
+
|
|
349
|
+
| Prop Name | Type / Structure | Description |
|
|
350
|
+
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
|
|
351
|
+
| `disableHeader` | `boolean` | Hide the chat header. |
|
|
352
|
+
| `disableMedia` | `boolean` | Disable media (file/image/audio) attachments. |
|
|
353
|
+
| `colors` | `{ primary: string; secondary: string }` | Primary/secondary color theme. |
|
|
354
|
+
| `googleLogin` | `{ enabled: boolean; firebaseConfig: FBConfig }` | Enable Google SSO and provide Firebase config. |
|
|
355
|
+
| `jwtLogin` | `{ token: string; enabled: boolean; handleBadlogin?: React.ReactElement }` | Enable JWT login and provide token. |
|
|
356
|
+
| `userLogin` | `{ enabled: boolean; user: User \| null }` | Enable user login and provide user object. |
|
|
357
|
+
| `customLogin` | `{ enabled: boolean; loginFunction: () => Promise<User \| null> }` | Enable custom login logic. |
|
|
358
|
+
| `baseUrl` | `string` | Custom API base URL. |
|
|
359
|
+
| `customAppToken` | `string` | Custom app token for API requests. |
|
|
360
|
+
| `xmppSettings` | `xmppSettingsInterface` | XMPP server settings. |
|
|
361
|
+
| `disableRooms` | `boolean` | Disable room list and force single-room mode. |
|
|
362
|
+
| `defaultLogin` | `boolean` | Use default login (for demo/testing). |
|
|
363
|
+
| `disableInteractions` | `boolean` | Disable all user interactions. |
|
|
364
|
+
| `chatHeaderBurgerMenu` | `boolean` | Show/hide burger menu in chat header. |
|
|
365
|
+
| `forceSetRoom` | `boolean` | Always show a specific room. |
|
|
366
|
+
| `roomListStyles` | `React.CSSProperties` | Custom styles for the room list. |
|
|
367
|
+
| `chatRoomStyles` | `React.CSSProperties` | Custom styles for the chat area. |
|
|
368
|
+
| `setRoomJidInPath` | `boolean` | Reflect room JID in the URL. |
|
|
369
|
+
| `disableRoomMenu` | `boolean` | Disable the room menu. |
|
|
370
|
+
| `defaultRooms` | `ConfigRoom[]` | List of default rooms to show. |
|
|
371
|
+
| `refreshTokens` | `{ enabled: boolean; refreshFunction?: () => Promise<{ accessToken: string; refreshToken?: string } \| null> }` | Enable token refresh logic. |
|
|
372
|
+
| `backgroundChat` | `{ color?: string; image?: string \| File }` | Set chat background color or image. |
|
|
373
|
+
| `bubleMessage` | `MessageBubble` | Custom message bubble component. |
|
|
374
|
+
| `headerLogo` | `string \| React.ReactElement` | Custom logo for the chat header. |
|
|
375
|
+
| `headerMenu` | `() => void` | Custom function for header menu. |
|
|
376
|
+
| `headerChatMenu` | `() => void` | Custom function for chat menu. |
|
|
377
|
+
| `customRooms` | `{ rooms: PartialRoomWithMandatoryKeys[]; disableGetRooms?: boolean; singleRoom: boolean }` | Custom room list and options. |
|
|
378
|
+
| `translates` | `{ enabled: boolean; translations?: Iso639_1Codes }` | Enable translation/localization. |
|
|
379
|
+
| `disableRoomConfig` | `boolean` | Disable room configuration. |
|
|
380
|
+
| `disableProfilesInteractions` | `boolean` | Disable profile interactions. |
|
|
381
|
+
| `disableUserCount` | `boolean` | Hide user count in the UI. |
|
|
382
|
+
| `clearStoreBeforeInit` | `boolean` | Clear Redux store before initialization. |
|
|
383
|
+
| `disableSentLogic` | `boolean` | Disable sent message logic. |
|
|
384
|
+
| `initBeforeLoad` | `boolean` | Initialize XMPP before loading UI. |
|
|
385
|
+
| `newArch` | `boolean` | Use new architecture for room management. |
|
|
386
|
+
| `qrUrl` | `string` | QR code URL for joining rooms. |
|
|
387
|
+
| `secondarySendButton` | `{ enabled: boolean; messageEdit: string; label?: React.ReactNode; buttonStyles?: React.CSSProperties; hideInputSendButton?: boolean; overwriteEnterClick?: true }` | Secondary send button config. |
|
|
388
|
+
| `enableRoomsRetry` | `{ enabled: boolean; helperText: string }` | Enable retry logic for room loading. |
|
|
389
|
+
| `disableNewChatButton` | `boolean` | Disable the new chat button. |
|
|
390
|
+
| `chatHeaderAdditional` | `{ enabled: boolean; element: any }` | Add additional element to chat header. |
|
|
391
|
+
| `botMessageAutoScroll` | `boolean` | Enable auto-scroll for bot messages. |
|
|
392
|
+
| `messageTextFilter` | `{ enabled: boolean; filterFunction: (text: string) => string }` | Filter/transform message text before sending. |
|
|
393
|
+
|
|
220
394
|
## Contacts, Documentation and Technical Support
|
|
221
395
|
|
|
222
396
|
- Community support forum: https://forum.ethora.com/
|
|
@@ -225,3 +399,122 @@ Supported by Ethora platform but not implemented into Chat Component yet:
|
|
|
225
399
|
- Documentation main: https://docs.ethora.com/
|
|
226
400
|
- Documentation for Ethora API (Swagger): https://api.ethoradev.com/api-docs
|
|
227
401
|
- Documentation on github including chat protocol and bots: https://github.com/dappros/ethora/tree/main/api
|
|
402
|
+
|
|
403
|
+
## Supported Environments
|
|
404
|
+
|
|
405
|
+
- Vite (React + TypeScript/JavaScript)
|
|
406
|
+
- Create React App
|
|
407
|
+
- Next.js (with client-side rendering)
|
|
408
|
+
- Electron (desktop apps)
|
|
409
|
+
- PWA (Progressive Web Apps)
|
|
410
|
+
- Any modern React setup (17+)
|
|
411
|
+
|
|
412
|
+
## Example Integrations
|
|
413
|
+
|
|
414
|
+
### 1. With Firebase Google SSO
|
|
415
|
+
|
|
416
|
+
```tsx
|
|
417
|
+
import { XmppProvider, Chat } from '@ethora/chat-component';
|
|
418
|
+
import firebaseConfig from './firebase-config';
|
|
419
|
+
|
|
420
|
+
const config = {
|
|
421
|
+
googleLogin: { enabled: true, firebaseConfig },
|
|
422
|
+
colors: { primary: '#4287f5', secondary: '#42f5e9' },
|
|
423
|
+
};
|
|
424
|
+
|
|
425
|
+
<XmppProvider config={config}>
|
|
426
|
+
<Chat />
|
|
427
|
+
</XmppProvider>;
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
### 2. With JWT Authentication
|
|
431
|
+
|
|
432
|
+
```tsx
|
|
433
|
+
const config = {
|
|
434
|
+
jwtLogin: { enabled: true, token: 'YOUR_JWT_TOKEN' },
|
|
435
|
+
};
|
|
436
|
+
<XmppProvider config={config}>
|
|
437
|
+
<Chat />
|
|
438
|
+
</XmppProvider>;
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
### 3. With Custom Login
|
|
442
|
+
|
|
443
|
+
```tsx
|
|
444
|
+
const config = {
|
|
445
|
+
customLogin: {
|
|
446
|
+
enabled: true,
|
|
447
|
+
loginFunction: async () => {
|
|
448
|
+
// Your custom login logic
|
|
449
|
+
return { xmppUsername: '...', xmppPassword: '...' };
|
|
450
|
+
},
|
|
451
|
+
},
|
|
452
|
+
};
|
|
453
|
+
<XmppProvider config={config}>
|
|
454
|
+
<Chat />
|
|
455
|
+
</XmppProvider>;
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
### 4. In a Next.js App (Client Component)
|
|
459
|
+
|
|
460
|
+
```tsx
|
|
461
|
+
'use client';
|
|
462
|
+
import { XmppProvider, Chat } from '@ethora/chat-component';
|
|
463
|
+
const config = { defaultLogin: true };
|
|
464
|
+
export default function Page() {
|
|
465
|
+
return (
|
|
466
|
+
<XmppProvider config={config}>
|
|
467
|
+
<Chat />
|
|
468
|
+
</XmppProvider>
|
|
469
|
+
);
|
|
470
|
+
}
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
## More Screenshots & GIFs
|
|
474
|
+
|
|
475
|
+
|
|
476
|
+
|
|
477
|
+
|
|
478
|
+
|
|
479
|
+
## Versioning & Upgrade Notes
|
|
480
|
+
|
|
481
|
+
- Follows [Semantic Versioning](https://semver.org/).
|
|
482
|
+
- See [Releases](https://github.com/dappros/ethora-chat-component/releases) for upgrade notes and breaking changes.
|
|
483
|
+
- For major upgrades, review the changelog and migration guide.
|
|
484
|
+
|
|
485
|
+
## Changelog & Release Notes
|
|
486
|
+
|
|
487
|
+
See [CHANGELOG.md](https://github.com/dappros/ethora-chat-component/blob/main/CHANGELOG.md) or the [GitHub Releases page](https://github.com/dappros/ethora-chat-component/releases) for details on new features, fixes, and improvements.
|
|
488
|
+
|
|
489
|
+
## Security
|
|
490
|
+
|
|
491
|
+
We take security seriously:
|
|
492
|
+
|
|
493
|
+
- All user input is validated and sanitized.
|
|
494
|
+
- XSS/CSRF protection is built-in.
|
|
495
|
+
- Auth tokens are never stored in plain text.
|
|
496
|
+
- Please [report vulnerabilities](https://www.ethora.com/#contact) responsibly.
|
|
497
|
+
|
|
498
|
+
## Contribution Guidelines
|
|
499
|
+
|
|
500
|
+
We welcome contributions! Please see our [CONTRIBUTING.md](https://github.com/dappros/ethora-chat-component/blob/main/CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](https://github.com/dappros/ethora-chat-component/blob/main/CODE_OF_CONDUCT.md) for details.
|
|
501
|
+
|
|
502
|
+
- Open issues or pull requests for bugs, features, or documentation.
|
|
503
|
+
- Join our [community forum](https://forum.ethora.com/) to discuss ideas.
|
|
504
|
+
|
|
505
|
+
## FAQ
|
|
506
|
+
|
|
507
|
+
**Q: How do I use my own Redux store?**
|
|
508
|
+
A: The component expects certain slices (`rooms`, `chatSettingStore`). You can adapt your store or use the provided one for quick start.
|
|
509
|
+
|
|
510
|
+
**Q: How do I customize the message bubble?**
|
|
511
|
+
A: Use the `CustomMessageComponent` prop. See [`src/components/ExampleComponents/CustomMessage.tsx`](https://github.com/dappros/ethora-chat-component/blob/main/src/components/ExampleComponents/CustomMessage.tsx).
|
|
512
|
+
|
|
513
|
+
**Q: How do I enable push notifications?**
|
|
514
|
+
A: This is planned for a future release. For now, you can integrate with your own notification system.
|
|
515
|
+
|
|
516
|
+
**Q: Can I use this in Electron or a PWA?**
|
|
517
|
+
A: Yes! The component works in Electron and PWA environments.
|
|
518
|
+
|
|
519
|
+
**Q: How do I report a bug or request a feature?**
|
|
520
|
+
A: Open an issue on GitHub or contact us via the [community forum](https://forum.ethora.com/).
|