@robylon/web-react-sdk 1.1.32-staging.1 → 1.1.32-staging.7

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.
Files changed (86) hide show
  1. package/README.md +515 -99
  2. package/dist/cjs/index.js +1 -1
  3. package/dist/cjs/index.js.map +1 -1
  4. package/dist/cjs/types/components/ChatbotContainer/ChatbotContainer.d.ts +5 -0
  5. package/dist/cjs/types/components/ChatbotFloatingButton.d.ts +3 -0
  6. package/dist/cjs/types/components/ChatbotIframe.d.ts +2 -0
  7. package/dist/cjs/types/components/RobylonChatbot.d.ts +6 -3
  8. package/dist/cjs/types/constants/fontStyles.d.ts +2 -0
  9. package/dist/cjs/types/core/api.d.ts +8 -0
  10. package/dist/cjs/types/core/config.d.ts +34 -0
  11. package/dist/cjs/types/core/events.d.ts +22 -0
  12. package/dist/cjs/types/core/index.d.ts +4 -0
  13. package/dist/cjs/types/core/state.d.ts +34 -0
  14. package/dist/cjs/types/index.d.ts +3 -0
  15. package/dist/cjs/types/types/events.d.ts +5 -0
  16. package/dist/cjs/types/types.d.ts +33 -0
  17. package/dist/cjs/types/utils/fetchData.d.ts +16 -0
  18. package/dist/cjs/types/vanilla/components/ChatbotContainer.d.ts +45 -0
  19. package/dist/cjs/types/vanilla/components/ChatbotFloatingButton.d.ts +72 -0
  20. package/dist/cjs/types/vanilla/components/ChatbotIframe.d.ts +73 -0
  21. package/dist/cjs/types/vanilla/index.d.ts +35 -0
  22. package/dist/esm/index.js +1 -1
  23. package/dist/esm/index.js.map +1 -1
  24. package/dist/esm/types/components/ChatbotContainer/ChatbotContainer.d.ts +5 -0
  25. package/dist/esm/types/components/ChatbotFloatingButton.d.ts +3 -0
  26. package/dist/esm/types/components/ChatbotIframe.d.ts +2 -0
  27. package/dist/esm/types/components/RobylonChatbot.d.ts +6 -3
  28. package/dist/esm/types/constants/fontStyles.d.ts +2 -0
  29. package/dist/esm/types/core/api.d.ts +8 -0
  30. package/dist/esm/types/core/config.d.ts +34 -0
  31. package/dist/esm/types/core/events.d.ts +22 -0
  32. package/dist/esm/types/core/index.d.ts +4 -0
  33. package/dist/esm/types/core/state.d.ts +34 -0
  34. package/dist/esm/types/index.d.ts +3 -0
  35. package/dist/esm/types/types/events.d.ts +5 -0
  36. package/dist/esm/types/types.d.ts +33 -0
  37. package/dist/esm/types/utils/fetchData.d.ts +16 -0
  38. package/dist/esm/types/vanilla/components/ChatbotContainer.d.ts +45 -0
  39. package/dist/esm/types/vanilla/components/ChatbotFloatingButton.d.ts +72 -0
  40. package/dist/esm/types/vanilla/components/ChatbotIframe.d.ts +73 -0
  41. package/dist/esm/types/vanilla/index.d.ts +35 -0
  42. package/dist/index.d.ts +77 -2
  43. package/dist/umd/robylon-chatbot.js +2 -0
  44. package/dist/umd/robylon-chatbot.js.map +1 -0
  45. package/dist/umd/types/components/ChatbotContainer/ChatbotContainer.d.ts +15 -0
  46. package/dist/umd/types/components/ChatbotContainer/index.d.ts +1 -0
  47. package/dist/umd/types/components/ChatbotFloatingButton.d.ts +15 -0
  48. package/dist/umd/types/components/ChatbotIframe.d.ts +14 -0
  49. package/dist/umd/types/components/ErrorBoundary.d.ts +15 -0
  50. package/dist/umd/types/components/RobylonChatbot.d.ts +14 -0
  51. package/dist/umd/types/config.d.ts +5 -0
  52. package/dist/umd/types/constants/errorConstants.d.ts +60 -0
  53. package/dist/umd/types/constants/fontStyles.d.ts +2 -0
  54. package/dist/umd/types/core/api.d.ts +8 -0
  55. package/dist/umd/types/core/config.d.ts +34 -0
  56. package/dist/umd/types/core/events.d.ts +22 -0
  57. package/dist/umd/types/core/index.d.ts +4 -0
  58. package/dist/umd/types/core/state.d.ts +34 -0
  59. package/dist/umd/types/hooks/useChatbot.d.ts +2 -0
  60. package/dist/umd/types/hooks/useChatbotEvents.d.ts +12 -0
  61. package/dist/umd/types/hooks/useChatbotState.d.ts +16 -0
  62. package/dist/umd/types/hooks/useWhyDidYouUpdate.d.ts +5 -0
  63. package/dist/umd/types/index.d.ts +6 -0
  64. package/dist/umd/types/services/ErrorTrackingService.d.ts +38 -0
  65. package/dist/umd/types/types/events.d.ts +27 -0
  66. package/dist/umd/types/types/state.d.ts +5 -0
  67. package/dist/umd/types/types.d.ts +71 -0
  68. package/dist/umd/types/utils/chatbotSdk.d.ts +23 -0
  69. package/dist/umd/types/utils/colorUtils.d.ts +1 -0
  70. package/dist/umd/types/utils/cookieUtils.d.ts +6 -0
  71. package/dist/umd/types/utils/environment.d.ts +12 -0
  72. package/dist/umd/types/utils/fetchData.d.ts +46 -0
  73. package/dist/umd/types/utils/logger.d.ts +6 -0
  74. package/dist/umd/types/utils/misc.d.ts +1 -0
  75. package/dist/umd/types/utils/originalFetchDataFile.d.ts +1 -0
  76. package/dist/umd/types/utils/systemInfo.d.ts +13 -0
  77. package/dist/umd/types/utils/version.d.ts +1 -0
  78. package/dist/umd/types/vanilla/components/ChatbotContainer.d.ts +45 -0
  79. package/dist/umd/types/vanilla/components/ChatbotFloatingButton.d.ts +72 -0
  80. package/dist/umd/types/vanilla/components/ChatbotIframe.d.ts +73 -0
  81. package/dist/umd/types/vanilla/index.d.ts +35 -0
  82. package/package.json +28 -9
  83. package/dist/cjs/types/types/config.d.ts +0 -33
  84. package/dist/cjs/types/types/index.d.ts +0 -16
  85. package/dist/esm/types/types/config.d.ts +0 -33
  86. package/dist/esm/types/types/index.d.ts +0 -16
package/README.md CHANGED
@@ -1,154 +1,570 @@
1
- # Robylon Web React SDK
2
-
3
- A lightweight React SDK for integrating Robylon's AI-powered chatbot into your web applications.
1
+ # Robylon SDK
2
+
3
+ The Robylon SDK provides an easy way to integrate a customizable chatbot into your application. This SDK supports both React applications and plain JavaScript/no-code websites.
4
+
5
+ ## Table of Contents
6
+
7
+ - [Installation](#installation)
8
+ - [React SDK Usage](#react-sdk-usage)
9
+ - [Basic Implementation](#react-basic-implementation)
10
+ - [External Triggers](#react-external-triggers)
11
+ - [Event Handling](#react-event-handling)
12
+ - [Plain JavaScript & No-Code Integration](#plain-javascript--no-code-integration)
13
+ - [Quick Embed (Easiest Method)](#quick-embed-easiest-method)
14
+ - [ES5/Google Tag Manager](#es5google-tag-manager)
15
+ - [Option 1: Quick Setup - Load with Page](#option-1-quick-setup---load-with-page)
16
+ - [Option 2: Reliable Loading - After DOM is Ready](#option-2-reliable-loading---after-dom-is-ready)
17
+ - [Option 3: User Context - Initialize After User Data](#option-3-user-context---initialize-after-user-data)
18
+ - [Configuration Options](#configuration-options)
19
+ - [Event Handling](#event-handling)
20
+ - [Customization](#customization)
21
+ - [Troubleshooting](#troubleshooting)
22
+ - [Platform-Specific Integration Guides](#platform-specific-integration-guides)
23
+ - [Webflow](#webflow-integration)
24
+ - [Wix](#wix-integration)
25
+ - [Shopify](#shopify-integration)
26
+ - [WordPress](#wordpress-integration)
27
+ - [Using the SDK from CDN](#using-the-sdk-from-cdn)
4
28
 
5
29
  ## Installation
6
30
 
31
+ ### For React applications:
32
+
7
33
  ```bash
8
34
  npm install @robylon/web-react-sdk
9
35
  # or
10
36
  yarn add @robylon/web-react-sdk
11
37
  ```
12
38
 
13
- ## Quick Start
39
+ ### For plain JavaScript and no-code websites:
40
+
41
+ Add this script to your website by copying and pasting the following code into the `<head>` section of your HTML:
42
+
43
+ ```html
44
+ <script src="https://cdn.robylon.ai/sdk/latest/chatbot.js"></script>
45
+ ```
46
+
47
+ #### Where to place the script:
48
+
49
+ 1. **For website builders (Wix, Squarespace, etc.):**
50
+
51
+ - Find your site editor or dashboard
52
+ - Look for "Custom Code", "Header Code", or "Site Settings" options
53
+ - Paste the script there, usually in a section labeled "Header" or "Head"
54
+
55
+ 2. **For custom HTML sites:**
56
+
57
+ - Open your website's HTML file in your editor
58
+ - Find the `<head>` section (it's near the top, between `<html>` and `<body>` tags)
59
+ - Paste the script tag just before the closing `</head>` tag
60
+
61
+ 3. **For WordPress:**
62
+ - Go to your WordPress dashboard
63
+ - Navigate to Appearance → Theme Editor or use a header/footer plugin
64
+ - Add the script to the header.php file before the closing `</head>` tag
65
+
66
+ > **Note:** Some of the integration options later in this guide will show different placements of this script - follow the specific example that best matches your needs.
67
+
68
+ ## React SDK Usage
69
+
70
+ ### React: Basic Implementation {#react-basic-implementation}
71
+
72
+ To use the Robylon SDK in a React application:
14
73
 
15
74
  ```jsx
16
75
  import { Chatbot } from "@robylon/web-react-sdk";
17
76
 
18
77
  function App() {
19
78
  const handleChatbotEvent = (event) => {
20
- logger.log(`Chatbot event: ${event.type}`, event);
79
+ console.log("Chatbot event:", event.type, event.data);
21
80
  };
22
81
 
23
82
  return (
24
- <Chatbot
25
- api_key="your-api-key"
26
- user_id="user-id"
27
- user_token="optional-auth-token"
28
- user_profile={{
29
- email: "user@example.com",
30
- name: "John Doe",
31
- mobile: "1234567890",
32
- }}
33
- onEvent={handleChatbotEvent}
34
- />
83
+ <div className="App">
84
+ <h1>My Website</h1>
85
+
86
+ <Chatbot
87
+ api_key="YOUR_API_KEY"
88
+ user_id="optional-user-id"
89
+ user_token="optional-auth-token"
90
+ user_profile={{
91
+ name: "Optional User Name",
92
+ email: "optional.email@example.com",
93
+ }}
94
+ onEvent={handleChatbotEvent}
95
+ />
96
+ </div>
35
97
  );
36
98
  }
99
+
100
+ export default App;
101
+ ```
102
+
103
+ ### React: Event Handling {#react-event-handling}
104
+
105
+ The React component accepts an `onEvent` prop for handling chatbot events:
106
+
107
+ ```jsx
108
+ <Chatbot
109
+ api_key="YOUR_API_KEY"
110
+ onEvent={(event) => {
111
+ switch (event.type) {
112
+ case "CHATBOT_LOADED":
113
+ console.log("Chatbot loaded");
114
+ break;
115
+ case "CHATBOT_OPENED":
116
+ console.log("Chatbot opened");
117
+ break;
118
+ case "CHATBOT_CLOSED":
119
+ console.log("Chatbot closed");
120
+ break;
121
+ // See the Supported Events section for all available events
122
+ }
123
+ }}
124
+ />
37
125
  ```
38
126
 
39
- ## Configuration
127
+ The `Chatbot` component renders a floating button that opens a chat interface when clicked. It handles all the communication with the Robylon backend services.
128
+
129
+ ### React: External Triggers {#react-external-triggers}
40
130
 
41
- ### Required Props
131
+ You can control the chatbot iframe from outside the component using a ref. This allows you to trigger open, close, or toggle actions from anywhere in your application:
42
132
 
43
- - `api_key`: Your Robylon API key
44
- - `user_id`: Unique identifier for the current user
133
+ ```jsx
134
+ import React, { useRef } from "react";
135
+ import { Chatbot, ChatbotRef } from "@robylon/web-react-sdk";
45
136
 
46
- ### Optional Props
137
+ function App() {
138
+ const chatbotRef = useRef < ChatbotRef > null;
47
139
 
48
- - `user_token`: Authentication token for the user
49
- - `user_profile`: Object containing user information
50
- - `email`: User's email address
51
- - `name`: User's name
52
- - `mobile`: User's mobile number
53
- - `onEvent`: Callback function to handle chatbot events
140
+ const showChatbot = () => {
141
+ chatbotRef.current?.show();
142
+ };
54
143
 
55
- ### Event Handling
144
+ const hideChatbot = () => {
145
+ chatbotRef.current?.hide();
146
+ };
56
147
 
57
- The SDK emits various events that you can listen to using the `onEvent` prop. Each event has the following structure:
148
+ const toggleChatbot = () => {
149
+ chatbotRef.current?.toggle();
150
+ };
58
151
 
59
- ```typescript
60
- interface ChatbotEvent {
61
- type: ChatbotEventType;
62
- timestamp: number;
63
- data?: any;
152
+ return (
153
+ <div className="App">
154
+ <h1>My Website</h1>
155
+
156
+ {/* External control buttons */}
157
+ <button onClick={showChatbot}>Show Chatbot</button>
158
+ <button onClick={hideChatbot}>Hide Chatbot</button>
159
+ <button onClick={toggleChatbot}>Toggle Chatbot</button>
160
+
161
+ <Chatbot
162
+ ref={chatbotRef}
163
+ api_key="YOUR_API_KEY"
164
+ user_id="optional-user-id"
165
+ onEvent={(event) => console.log("Chatbot event:", event)}
166
+ />
167
+ </div>
168
+ );
64
169
  }
65
170
  ```
66
171
 
67
- Available event types:
172
+ #### Available External Methods
68
173
 
69
- ```typescript
70
- enum ChatbotEventType {
71
- CHATBOT_BUTTON_LOADED = "CHATBOT_BUTTON_LOADED", // When the chat button is rendered
72
- CHATBOT_OPENED = "CHATBOT_OPENED", // When chat window is opened
73
- CHATBOT_CLOSED = "CHATBOT_CLOSED", // When chat window is closed
74
- CHATBOT_APP_READY = "CHATBOT_APP_READY", // When SDK is fully initialized
75
- CHATBOT_LOADED = "CHATBOT_LOADED", // When chatbot iframe is loaded
76
- CHAT_INITIALIZED = "CHAT_INITIALIZED", // When chat session is initialized
77
- SESSION_REFRESHED = "SESSION_REFRESHED", // When chat session is refreshed
78
- CHAT_INITIALIZATION_FAILED = "CHAT_INITIALIZATION_FAILED", // When initialization fails
79
- }
174
+ | Method | Description |
175
+ | ---------- | ------------------------------------------------- |
176
+ | `show()` | Opens the chatbot iframe if it's currently closed |
177
+ | `hide()` | Closes the chatbot iframe if it's currently open |
178
+ | `toggle()` | Toggles the chatbot iframe visibility |
179
+
180
+ #### Event Handling with External Triggers
181
+
182
+ External trigger methods emit the same events as internal triggers:
183
+
184
+ - `CHATBOT_BUTTON_CLICKED` - When `show()` or `toggle()` opens the chatbot
185
+ - `CHATBOT_CLOSED` - When `hide()` or `toggle()` closes the chatbot
186
+
187
+ This ensures consistent event handling regardless of how the chatbot is triggered.
188
+
189
+ ## Plain JavaScript & No-Code Integration
190
+
191
+ > **IMPORTANT:** You will need an API key from Robylon for any integration to work.
192
+
193
+ ### Quick Embed (Easiest Method)
194
+
195
+ This is the simplest way to add the Robylon chatbot to any website with a single line of code. Just copy and paste this script tag into your HTML:
196
+
197
+ ```
198
+ <script>(function(k){window.R=window.R||function(){(window.R.q=window.R.q||[]).push(arguments)};window.R=new Proxy(window.R,{get:(t,p)=>p==="q"?t.q:(...a)=>t(p,...a)});function l(){var s=document.createElement("script");s.src="https://cdn.robylon.ai/sdk/latest/chatbot.js";s.onload=()=>k&&window.RobylonChatbot.create({api_key:k});document.body.appendChild(s)}document.readyState==="complete"?l():window.addEventListener("load",l)})("YOUR_API_KEY_HERE");</script>
80
199
  ```
81
200
 
82
- Example usage:
201
+ Just replace `YOUR_API_KEY_HERE` with your actual Robylon API key, and you're done! No additional code is needed.
83
202
 
84
- ```jsx
85
- function App() {
86
- const handleChatbotEvent = (event) => {
203
+ ### ES5/Google Tag Manager
204
+
205
+ #### ES5 Compatible Version
206
+
207
+ For older browsers that don't support ES6 features, use this ES5 compatible version:
208
+
209
+ ```
210
+ <script>(function(a){window.R=window.R||function(){(window.R.q=window.R.q||[]).push(Array.prototype.slice.call(arguments))};window.R.show=function(){window.R('show')};window.R.hide=function(){window.R('hide')};window.R.toggle=function(){window.R('toggle')};window.R.track=function(){window.R('track',Array.prototype.slice.call(arguments))};var o=function(){var s=document.createElement("script");s.src="https://cdn.robylon.ai/sdk/latest/chatbot.js";s.id="robylon-chatbot-sdk";s.onload=function(){if(a){window.RobylonChatbot.create({api_key:a})}};document.body.appendChild(s)};if(document.readyState==="complete"){o()}else{window.addEventListener("load",o)}})("YOUR_API_KEY_HERE");</script>
211
+ ```
212
+
213
+ This version is compatible with Internet Explorer 11 and other older browsers that don't support ES6 features like arrow functions, `const`/`let`, and Proxy objects.
214
+
215
+ #### Quick Embed with Custom Position and Spacing
216
+
217
+ If you want to customize the position and spacing of the chatbot button, you can use this alternative version:
218
+
219
+ ```
220
+ <script>(function(k,p,side,bottom){window.R=window.R||function(){(window.R.q=window.R.q||[]).push(arguments)};window.R=new Proxy(window.R,{get:(t,p)=>p==="q"?t.q:(...a)=>t(p,...a)});function l(){var s=document.createElement("script");s.src="https://cdn.robylon.ai/sdk/latest/chatbot.js";s.onload=()=>k&&window.RobylonChatbot.create({api_key:k,position:p,sideSpacing:side,bottomSpacing:bottom});document.body.appendChild(s)}document.readyState==="complete"?l():window.addEventListener("load",l)})("YOUR_API_KEY_HERE","Left",30,25);</script>
221
+ ```
222
+
223
+ Just replace:
224
+
225
+ - `YOUR_API_KEY_HERE` with your actual API key
226
+ - `"Left"` with `"Left"` or `"Right"` for button position
227
+ - `30` with your desired side spacing in pixels
228
+ - `25` with your desired bottom spacing in pixels
229
+
230
+ ##### ES5 Compatible Version with Custom Position and Spacing
231
+
232
+ For older browsers, use this ES5 compatible version with custom positioning:
233
+
234
+ ```
235
+ <script>(function(a,p,s,b){window.R=window.R||function(){(window.R.q=window.R.q||[]).push(Array.prototype.slice.call(arguments))};window.R.show=function(){window.R('show')};window.R.hide=function(){window.R('hide')};window.R.toggle=function(){window.R('toggle')};window.R.track=function(){window.R('track',Array.prototype.slice.call(arguments))};var o=function(){var s=document.createElement("script");s.src="https://cdn.robylon.ai/sdk/latest/chatbot.js";s.id="robylon-chatbot-sdk";s.onload=function(){if(a){window.RobylonChatbot.create({api_key:a,position:p,sideSpacing:s,bottomSpacing:b})}};document.body.appendChild(s)};if(document.readyState==="complete"){o()}else{window.addEventListener("load",o)}})("YOUR_API_KEY_HERE","Left",30,25);</script>
236
+ ```
237
+
238
+ Replace the same parameters as above for the ES5 compatible version.
239
+
240
+ #### Where to place the script:
241
+
242
+ - At the end of your HTML `<body>` section for best performance
243
+ - Or anywhere in your HTML code if you're using a website builder
244
+
245
+ There are several other ways to add the Robylon chatbot to your website or no-code platform, depending on your needs:
246
+
247
+ ### Option 1: Quick Setup - Load with Page
248
+
249
+ This is the simplest approach for any website. The chatbot loads while the page is loading but doesn't block the page from appearing.
250
+
251
+ #### What to copy:
252
+
253
+ 1️⃣ **Add this to your HTML `<head>` section:**
254
+
255
+ ```html
256
+ <script
257
+ src="https://cdn.robylon.ai/sdk/latest/robylon-chatbot.js"
258
+ defer
259
+ ></script>
260
+ <script>
261
+ // Initialize when page is ready
262
+ document.addEventListener("DOMContentLoaded", () => {
263
+ RobylonChatbot.create({
264
+ api_key: "YOUR_API_KEY", // Replace with your actual API key
265
+ user_id: "optional-user-id", // Optional: remove if not needed
266
+ user_profile: {
267
+ name: "Optional User Name", // Optional: remove if not needed
268
+ email: "optional.email@example.com", // Optional: remove if not needed
269
+ },
270
+ });
271
+ });
272
+ </script>
273
+ ```
274
+
275
+ #### Complete example:
276
+
277
+ ```html
278
+ <!DOCTYPE html>
279
+ <html>
280
+ <head>
281
+ <title>Robylon SDK - Quick Setup</title>
282
+ <!-- COPY FROM HERE -->
283
+ <script
284
+ src="https://cdn.robylon.ai/sdk/latest/robylon-chatbot.js"
285
+ defer
286
+ ></script>
287
+ <script>
288
+ // Initialize when page is ready
289
+ document.addEventListener("DOMContentLoaded", () => {
290
+ RobylonChatbot.create({
291
+ api_key: "YOUR_API_KEY", // Replace with your actual API key
292
+ user_id: "optional-user-id", // Optional: remove if not needed
293
+ user_profile: {
294
+ name: "Optional User Name", // Optional: remove if not needed
295
+ email: "optional.email@example.com", // Optional: remove if not needed
296
+ },
297
+ });
298
+ });
299
+ </script>
300
+ <!-- COPY UNTIL HERE -->
301
+ </head>
302
+ <body>
303
+ <h1>Your Website Content</h1>
304
+ <!-- Your website content here -->
305
+ </body>
306
+ </html>
307
+ ```
308
+
309
+ ### Option 2: Reliable Loading - After DOM is Ready
310
+
311
+ This approach ensures the chatbot only initializes after your page is fully loaded, making it more reliable for websites with complex layouts.
312
+
313
+ #### What to copy:
314
+
315
+ 1️⃣ **Add this to your HTML `<head>` section:**
316
+
317
+ ```html
318
+ <script src="https://cdn.robylon.ai/sdk/latest/robylon-chatbot.js"></script>
319
+ ```
320
+
321
+ 2️⃣ **Add this at the end of your HTML `<body>` section:**
322
+
323
+ ```html
324
+ <script>
325
+ // Wait for page to be fully loaded before showing chatbot
326
+ document.addEventListener("DOMContentLoaded", () => {
327
+ RobylonChatbot.create({
328
+ api_key: "YOUR_API_KEY", // Replace with your actual API key
329
+ user_id: "optional-user-id", // Optional: remove if not needed
330
+ user_profile: {
331
+ name: "Optional User Name", // Optional: remove if not needed
332
+ email: "optional.email@example.com", // Optional: remove if not needed
333
+ },
334
+ });
335
+ });
336
+ </script>
337
+ ```
338
+
339
+ #### Complete example:
340
+
341
+ ```html
342
+ <!DOCTYPE html>
343
+ <html>
344
+ <head>
345
+ <title>Robylon SDK - Reliable Loading</title>
346
+ <!-- COPY FROM HERE -->
347
+ <script src="https://cdn.robylon.ai/sdk/latest/robylon-chatbot.js"></script>
348
+ <!-- COPY UNTIL HERE -->
349
+ </head>
350
+ <body>
351
+ <h1>Your Website Content</h1>
352
+ <!-- Your website content here -->
353
+
354
+ <script>
355
+ // Wait for page to be fully loaded before showing chatbot
356
+ document.addEventListener("DOMContentLoaded", () => {
357
+ RobylonChatbot.create({
358
+ api_key: "YOUR_API_KEY", // Replace with your actual API key
359
+ user_id: "optional-user-id", // Optional: remove if not needed
360
+ user_profile: {
361
+ name: "Optional User Name", // Optional: remove if not needed
362
+ email: "optional.email@example.com", // Optional: remove if not needed
363
+ },
364
+ });
365
+ });
366
+ </script>
367
+ </body>
368
+ </html>
369
+ ```
370
+
371
+ ### Option 3: User Context - Initialize After User Data
372
+
373
+ This approach loads the chatbot after user data is available. Great for websites where you want to personalize the chat experience.
374
+
375
+ #### What to copy:
376
+
377
+ 1️⃣ **Add this to your HTML `<head>` section:**
378
+
379
+ ```html
380
+ <script
381
+ src="https://cdn.robylon.ai/sdk/latest/robylon-chatbot.js"
382
+ defer
383
+ ></script>
384
+ ```
385
+
386
+ 2️⃣ **Add this script at the end of your HTML `<body>` section:**
387
+
388
+ ```html
389
+ <script>
390
+ // Wait for page to be ready
391
+ document.addEventListener("DOMContentLoaded", () => {
392
+ // Get your user data (replace this with your own method)
393
+ getUserData().then((user) => {
394
+ // Initialize chatbot with user info
395
+ RobylonChatbot.create({
396
+ api_key: "YOUR_API_KEY", // Replace with your actual API key
397
+ user_id: user.id,
398
+ user_profile: {
399
+ name: user.name,
400
+ email: user.email,
401
+ },
402
+ });
403
+ });
404
+ });
405
+
406
+ // Example function to get user data - replace with your own
407
+ function getUserData() {
408
+ // This is just a placeholder - replace with your actual code
409
+ return Promise.resolve({
410
+ id: "user123",
411
+ name: "Jane Smith",
412
+ email: "jane@example.com",
413
+ });
414
+ }
415
+ </script>
416
+ ```
417
+
418
+ #### Complete example:
419
+
420
+ ```html
421
+ <!DOCTYPE html>
422
+ <html>
423
+ <head>
424
+ <title>My Website</title>
425
+ <!-- COPY FROM HERE -->
426
+ <script
427
+ src="https://cdn.robylon.ai/sdk/latest/robylon-chatbot.js"
428
+ defer
429
+ ></script>
430
+ <!-- COPY UNTIL HERE -->
431
+ </head>
432
+ <body>
433
+ <h1>Your Website Content</h1>
434
+ <!-- Your website content here -->
435
+
436
+ <!-- COPY FROM HERE -->
437
+ <script>
438
+ // Wait for page to be ready
439
+ document.addEventListener("DOMContentLoaded", () => {
440
+ // Get your user data (replace this with your own method)
441
+ getUserData().then((user) => {
442
+ // Initialize chatbot with user info
443
+ RobylonChatbot.create({
444
+ api_key: "YOUR_API_KEY", // Replace with your actual API key
445
+ user_id: user.id,
446
+ user_profile: {
447
+ name: user.name,
448
+ email: user.email,
449
+ },
450
+ });
451
+ });
452
+ });
453
+
454
+ // Example function to get user data - replace with your own
455
+ function getUserData() {
456
+ // This is just a placeholder - replace with your actual code
457
+ return Promise.resolve({
458
+ id: "user123",
459
+ name: "Jane Smith",
460
+ email: "jane@example.com",
461
+ });
462
+ }
463
+ </script>
464
+ <!-- COPY UNTIL HERE -->
465
+ </body>
466
+ </html>
467
+ ```
468
+
469
+ ### Plain JS & No-Code: Event Handling
470
+
471
+ You can handle chatbot events in plain JavaScript using the `onEvent` callback:
472
+
473
+ #### What to copy:
474
+
475
+ ```javascript
476
+ const chatbot = RobylonChatbot.create({
477
+ api_key: "YOUR_API_KEY", // Replace with your actual API key
478
+ onEvent: function (event) {
87
479
  switch (event.type) {
88
- case "CHATBOT_BUTTON_CLICKED":
89
- logger.log("Chat button clicked at:", new Date(event.timestamp));
480
+ case "CHATBOT_LOADED":
481
+ console.log("Chatbot loaded");
90
482
  break;
91
483
  case "CHATBOT_OPENED":
92
- logger.log("Chat window opened at:", new Date(event.timestamp));
484
+ console.log("Chatbot opened");
93
485
  break;
94
- case "CHAT_INITIALIZED":
95
- logger.log("Chat session initialized");
96
- break;
97
- case "CHAT_INITIALIZATION_FAILED":
98
- console.error("Chat initialization failed:", event.data);
486
+ case "CHATBOT_CLOSED":
487
+ console.log("Chatbot closed");
99
488
  break;
489
+ // See the Supported Events section for all available events
100
490
  }
101
- };
102
-
103
- return (
104
- <Chatbot
105
- api_key="your-api-key"
106
- user_id="user-id"
107
- onEvent={handleChatbotEvent}
108
- />
109
- );
110
- }
111
- ```
491
+ },
492
+ });
112
493
 
113
- ### Automatically Included Information
494
+ // The chatbot instance provides methods to control the chatbot
495
+ // chatbot.show(); // Show the chatbot
496
+ // chatbot.hide(); // Hide the chatbot
497
+ // chatbot.toggle(); // Toggle visibility
498
+ // chatbot.destroy(); // Remove the chatbot from the page
114
499
 
115
- The SDK automatically collects and includes the following system information:
116
-
117
- - `platform`: Always set to "web"
118
- - `os`: User's operating system
119
- - `browser`: User's browser type
120
- - `device`: Device type (desktop/mobile/tablet)
121
- - `screen_size`: User's screen dimensions (width and height)
122
- - `sdk_version`: Current version of the SDK
500
+ > **Note:** The plain JavaScript SDK provides direct instance methods for external control. The React SDK provides similar functionality through refs (see [React External Triggers](#react-external-triggers) section above).
501
+ ```
123
502
 
124
- ## Features
503
+ ## Configuration Options
125
504
 
126
- - Persistent chat interface
127
- - Responsive design for all screen sizes
128
- - Automatic system information collection
129
- - Customizable chat bubble
130
- - Session management
131
- - Secure communication channel
132
- - Cross-browser compatibility
133
- - Comprehensive event system
505
+ The SDK supports the following configuration options for both React and plain JavaScript implementations. **Note:** The React SDK also supports external triggers via refs for programmatic control of the chatbot iframe.
134
506
 
135
- ## Browser Support
507
+ | Option | Type | Description | Required/Optional |
508
+ | ------------- | -------- | ----------------------------------------------- | ----------------- |
509
+ | api_key | string | Your Robylon API key | Required |
510
+ | user_id | string | User identifier for conversation tracking | Optional |
511
+ | user_token | string | Authentication token | Optional |
512
+ | user_profile | object | Additional user information | Optional |
513
+ | onEvent | function | Event handler for chatbot interactions | Optional |
514
+ | position | string | Position of the chatbot button ("Left"/"Right") | Optional |
515
+ | sideSpacing | number | Distance from the side of the screen (in px) | Optional |
516
+ | bottomSpacing | number | Distance from the bottom of the screen (in px) | Optional |
136
517
 
137
- The SDK supports all modern browsers and includes fallbacks for:
518
+ ### Position and Spacing Configuration
138
519
 
139
- - User agent detection
140
- - Screen size detection
141
- - Browser identification
142
- - Device type detection
520
+ You can control the position and spacing of the chatbot button either through the API configuration or directly in the SDK. If both are provided, the SDK configuration takes precedence.
143
521
 
144
- ## Development
522
+ #### React Example:
145
523
 
146
- ### Creating Branches
524
+ ```jsx
525
+ <Chatbot
526
+ api_key="YOUR_API_KEY"
527
+ position="Left"
528
+ sideSpacing={30}
529
+ bottomSpacing={25}
530
+ />
531
+ ```
147
532
 
148
- Always use the provided script to create new branches:
533
+ #### Plain JavaScript Example:
149
534
 
150
- ```bash
151
- npm run branch
535
+ ```javascript
536
+ RobylonChatbot.create({
537
+ api_key: "YOUR_API_KEY",
538
+ position: "Left",
539
+ sideSpacing: 30,
540
+ bottomSpacing: 25,
541
+ });
152
542
  ```
153
543
 
154
- This ensures proper version control and naming conventions.
544
+ ## Event Handling
545
+
546
+ ### Supported Events
547
+
548
+ The SDK emits the following events that you can listen for in both React and plain JavaScript implementations:
549
+
550
+ | Event Type | Description | Data |
551
+ | ---------------------------- | ----------------------------------------------- | ---------------------------------------- |
552
+ | `CHATBOT_BUTTON_LOADED` | The chatbot button has been loaded and rendered | - |
553
+ | `CHATBOT_LOADED` | The chatbot iframe has been loaded | - |
554
+ | `CHATBOT_OPENED` | The chatbot has been opened | - |
555
+ | `CHATBOT_CLOSED` | The chatbot has been closed | - |
556
+ | `CHAT_INITIALIZED` | The chat session has been initialized | - |
557
+ | `CHAT_INITIALIZATION_FAILED` | The chat session failed to initialize | `{ error: string }` |
558
+ | `SESSION_REFRESHED` | The chat session has been refreshed | - |
559
+ | `MESSAGE_SENT` | User has sent a message | `{ message: string }` |
560
+ | `MESSAGE_RECEIVED` | A message was received from the chatbot | `{ message: string }` |
561
+ | `CONVERSATION_STARTED` | A new conversation has started | `{ conversationId: string }` |
562
+ | `CONVERSATION_ENDED` | The current conversation has ended | `{ conversationId: string }` |
563
+ | `USER_AUTHENTICATED` | The user has been authenticated | `{ userId: string }` |
564
+ | `USER_PROFILE_UPDATED` | The user profile has been updated | `{ profile: object }` |
565
+ | `USER_FEEDBACK_SUBMITTED` | The user has submitted feedback | `{ rating: number, comment: string }` |
566
+ | `FILE_UPLOAD_STARTED` | A file upload has started | `{ fileName: string, fileSize: number }` |
567
+ | `FILE_UPLOAD_COMPLETED` | A file upload has completed | `{ fileName: string, fileUrl: string }` |
568
+ | `FILE_UPLOAD_FAILED` | A file upload has failed | `{ fileName: string, error: string }` |
569
+
570
+ | `CHATBOT_ERROR`