🤖 TimeSaverBot Website Widget

1. Introduction

TimeSaverBot Website Widget is a chat widget for integration into your website. The widget uses iframe technology for complete isolation from JavaScript errors on the parent page, ensuring stable operation even when there are errors on the site.

Key Features

• Complete isolation from page errors
• SignalR works inside iframe
• Secure communication via PostMessage API
• Responsive design for mobile devices
• Theme support (light/dark)
• Multi-language support
• Message history
• File and image uploads
• Typing indicator
• Server-side customization settings (title, colors, position)

2. Quick Start

Minimal Integration

Add the following code before the closing </body> tag on your page:

<script src="https://widget.timesaverbot.com/embed.js"
        data-tenant-id="your-tenant-id"
        data-channel-id="5">
</script>

The widget will automatically load and display in the bottom right corner of the page.

3. Basic Connection

HTML Attributes (Recommended Method)

The simplest way to connect is using data-attributes in the <script> tag:

<script src="https://widget.timesaverbot.com/embed.js"
        data-tenant-id="qa"
        data-channel-id="5"
        data-user-id="35443435"
        data-user-name="Andrey Test"
        data-user-phone="34534534534345"
        data-user-email="[email protected]"
        data-user-key1="35345345"
        data-user-key2="true"
        data-user-key3="Test 11">
</script>

Programmatic Initialization

If you need more control, you can initialize the widget programmatically:

<script src="https://widget.timesaverbot.com/embed.js"></script>
<script>
    BotCraft.init({
        tenantId: 'your-tenant-id',
        channelId: '5',
        apiUrl: 'https://api.timesaverbot.com',
        widgetUrl: 'https://widget.timesaverbot.com',
        userId: 'user123',
        theme: 'light',
        language: 'en',
        position: 'bottom-right'
    });
</script>

4. Configuration Parameters

Required Parameters

Optional Parameters

Complete Configuration Example

<script src="https://widget.timesaverbot.com/embed.js"
        data-tenant-id="qa"
        data-channel-id="5"
        data-api-url="https://api.timesaverbot.com"
        data-widget-url="https://widget.timesaverbot.com"
        data-user-id="35443435"
        data-position="bottom-right"
        data-theme="light"
        data-language="ru"
        data-auto-init="true">
</script>

5. Server-Side Customization Settings

In addition to embed script parameters, the widget supports server-side settings that the administrator configures in the TimeSaverBot control panel. These settings have priority over embed script parameters and are applied automatically when the widget connects.

Available Server-Side Settings

How to Change Settings via Admin Panel

1. Open the channels section - Navigate to Settings → Connectors
2. Select WebChat channel - Find the WebChat type channel in the list and click on it
3. Configure widget parameters
   • Language - Select interface language from 83+ locales or leave "Auto-detect"
   • Position - Choose widget location: "Bottom Right" or "Bottom Left"
   • Header Title - Enter widget header title (e.g., "Support" or "Chat")
   • Header Background Color - Choose header background color via color picker
   • Side Padding (px) - Specify side padding from screen edge in pixels (e.g., 20)
   • Bottom Padding (px) - Specify bottom padding from screen edge in pixels (e.g., 20)
   • Toggle Button Color - Choose widget toggle button color via color picker
4. Save changes - Click the Save button and wait for success notification
5. Test changes - Refresh the page with the widget; settings will apply to new sessions automatically

Settings Priority

1. Server-side settings (from Channel.Data) - highest priority
2. Embed script parameters - applied if server settings are not defined
3. Default values - fallback

6. User Data

The widget supports passing additional user data via data-attributes. This data can be used for personalization and user identification.

Standard User Fields

Custom Fields (Custom Keys)

You can pass additional custom data via attributes data-user-key1, data-user-key2, data-user-key3, etc.:

<script src="https://widget.timesaverbot.com/embed.js"
        data-tenant-id="qa"
        data-channel-id="5"
        data-user-id="35443435"
        data-user-name="Andrey Test"
        data-user-phone="34534534534345"
        data-user-email="[email protected]"
        data-user-key1="35345345"
        data-user-key2="true"
        data-user-key3="Test 11">
</script>

Dynamic User Data Update

If user data changes during a session, you can update the widget configuration:

BotCraft.init({
    tenantId: 'qa',
    channelId: '5',
    userId: 'new-user-id',
    // ... other parameters
});

7. Programmatic API

After the widget loads, a global BotCraft object is available with methods for widget management.

Control Methods

BotCraft.init(config)

Initializes the widget with the specified configuration.

Parameters:

• config (Object) - configuration object

Returns: boolean - true on successful initialization

const success = BotCraft.init({
    tenantId: 'qa',
    channelId: '5',
    userId: 'user123'
});

BotCraft.open()

Opens the chat widget.

BotCraft.open();

BotCraft.close()

Closes the chat widget.

BotCraft.close();

BotCraft.sendMessage(message)

Sends a message on behalf of the user programmatically.

Parameters:

• message (string) - message text

BotCraft.sendMessage('Hello from JavaScript!');

BotCraft.getStatus()

Gets the current widget status.

Returns: null (status is sent via status event)

BotCraft.getStatus();

BotCraft.on(event, callback)

Subscribes to a widget event.

Parameters:

• event (string) - event name
• callback (Function) - handler function

BotCraft.on('ready', function() {
    console.log('Widget is ready!');
});

BotCraft.off(event, callback)

Unsubscribes from a widget event.

Parameters:

• event (string) - event name
• callback (Function) - handler function

const handler = function() { console.log('Ready'); };
BotCraft.on('ready', handler);
// Later...
BotCraft.off('ready', handler);

8. Widget Events

The widget generates events that you can subscribe to for state tracking and interaction.

Available Events

ready

Triggered when the widget is fully loaded and ready to work.

BotCraft.on('ready', function() {
    console.log('Widget is ready to use');
});

open

Triggered when the user opens the widget.

BotCraft.on('open', function() {
    console.log('Widget opened');
    // Can track analytics
    gtag('event', 'chat_widget_opened');
});

close

Triggered when the user closes the widget.

BotCraft.on('close', function() {
    console.log('Widget closed');
});

status

Triggered when the widget status changes.

BotCraft.on('status', function(data) {
    console.log('Widget status:', data);
    // data contains: { isOpen: boolean, isConnected: boolean, messageCount: number }
});

Analytics Integration Example

// Google Analytics
BotCraft.on('open', function() {
    gtag('event', 'chat_widget_opened', {
        'event_category': 'engagement',
        'event_label': 'widget'
    });
});

BotCraft.on('close', function() {
    gtag('event', 'chat_widget_closed', {
        'event_category': 'engagement',
        'event_label': 'widget'
    });
});

// Yandex Metrica
BotCraft.on('open', function() {
    ym(12345678, 'reachGoal', 'chat_widget_opened');
});

9. Usage Examples

Example 1: Basic Integration for E-commerce

<!DOCTYPE html>
<html>
<head>
    <title>My Store</title>
</head>
<body>
    <!-- Site content -->

    <!-- TimeSaverBot Widget -->
    <script src="https://widget.timesaverbot.com/embed.js"
            data-tenant-id="store-tenant"
            data-channel-id="5"
            data-theme="light"
            data-language="en">
    </script>

    <script>
        // Automatically open widget after 30 seconds
        BotCraft.on('ready', function() {
            setTimeout(function() {
                BotCraft.open();
            }, 30000);
        });
    </script>
</body>
</html>

Example 2: Integration with Authenticated User

<script src="https://widget.timesaverbot.com/embed.js"
        data-tenant-id="qa"
        data-channel-id="5"
        data-user-id="<?php echo $user->id; ?>"
        data-user-name="<?php echo htmlspecialchars($user->name); ?>"
        data-user-email="<?php echo htmlspecialchars($user->email); ?>"
        data-user-phone="<?php echo htmlspecialchars($user->phone); ?>">
</script>

Example 3: Programmatic Widget Control

<script src="https://widget.timesaverbot.com/embed.js"
        data-tenant-id="qa"
        data-channel-id="5"
        data-auto-init="false">
</script>

<script>
    // Delayed initialization
    setTimeout(function() {
        BotCraft.init({
            tenantId: 'qa',
            channelId: '5',
            userId: 'user123',
            theme: 'dark',
            language: 'en'
        });
    }, 1000);

    // Open widget on button click
    document.getElementById('open-chat-btn').addEventListener('click', function() {
        BotCraft.open();
    });

    // Send message programmatically
    document.getElementById('send-message-btn').addEventListener('click', function() {
        BotCraft.sendMessage('Hello! I need help.');
        BotCraft.open();
    });
</script>

Example 4: Event Tracking for Analytics

<script src="https://widget.timesaverbot.com/embed.js"
        data-tenant-id="qa"
        data-channel-id="5">
</script>

<script>
    // Track widget opening
    BotCraft.on('ready', function() {
        console.log('Widget loaded');
    });

    BotCraft.on('open', function() {
        // Google Analytics
        if (typeof gtag !== 'undefined') {
            gtag('event', 'chat_widget_opened');
        }

        // Yandex Metrica
        if (typeof ym !== 'undefined') {
            ym(12345678, 'reachGoal', 'chat_opened');
        }

        console.log('User opened chat');
    });

    BotCraft.on('close', function() {
        console.log('User closed chat');
    });

    BotCraft.on('status', function(data) {
        console.log('Widget status:', data);
        // data.isOpen - is widget open
        // data.isConnected - is connected to server
        // data.messageCount - number of messages
    });
</script>

Example 5: Conditional Widget Display

<script src="https://widget.timesaverbot.com/embed.js"
        data-tenant-id="qa"
        data-channel-id="5"
        data-auto-init="false">
</script>

<script>
    // Show widget only on certain pages
    const allowedPages = ['/contact', '/support', '/help'];
    const currentPath = window.location.pathname;

    if (allowedPages.includes(currentPath)) {
        BotCraft.init({
            tenantId: 'qa',
            channelId: '5'
        });
    }

    // Or show only for authenticated users
    if (window.user && window.user.isAuthenticated) {
        BotCraft.init({
            tenantId: 'qa',
            channelId: '5',
            userId: window.user.id,
            userName: window.user.name,
            userEmail: window.user.email
        });
    }
</script>

10. Troubleshooting

Widget Does Not Load

Solutions:

1. Check the browser console for errors (F12 → Console)
2. Ensure data-tenant-id is specified correctly
3. Check that the widget URL is accessible and not blocked
4. Ensure the script loads before the closing </body> tag
5. Check network requests in DevTools (F12 → Network)

// Check widget loading
if (typeof BotCraft === 'undefined') {
    console.error('Widget not loaded');
} else {
    console.log('Widget loaded:', BotCraft.isReady);
}

SignalR Connection Issues

Solutions:

1. Check correctness of data-api-url or apiUrl
2. Ensure server is accessible and not blocked by firewall
3. Check WebSocket support in browser
4. Verify authentication token (if used)

BotCraft.on('status', function(data) {
    if (!data.isConnected) {
        console.error('Widget not connected to server');
    }
});

Widget Does Not Open

Solutions:

1. Check that widget is initialized: BotCraft.isReady
2. Try opening programmatically: BotCraft.open()
3. Check console for errors
4. Ensure iframe is not blocked by security policy

BotCraft.on('ready', function() {
    console.log('Widget ready');
    // Try opening programmatically
    setTimeout(function() {
        BotCraft.open();
    }, 1000);
});

User Data Issues

Solutions:

1. Ensure attributes are specified correctly (e.g., data-user-name, not data-userName)
2. Check that values don't contain special characters without escaping
3. For dynamic data, use programmatic initialization

<!-- Correct -->
<script src="..." data-user-name="John Doe" data-user-email="[email protected]"></script>

<!-- Incorrect -->
<script src="..." data-userName="John Doe"></script>

Positioning Issues

Solutions:

1. Check data-position value (allowed: bottom-right, bottom-left, top-right, top-left)
2. Ensure there's no CSS on the page that overlaps the widget
3. Check z-index of other elements

<script src="..." data-position="bottom-left"></script>

Theme and Language Issues

Solutions:

1. Check data-theme value (light or dark)
2. Check data-language value (supported: en, ru, he)
3. Ensure values are in lowercase

<script src="..." data-theme="dark" data-language="en"></script>

Widget Conflicts with Other Scripts

Solutions:

1. Widget uses iframe, so it's isolated from page errors
2. If the problem persists, try loading the widget asynchronously
3. Use programmatic initialization with delay

(function() {
    const script = document.createElement('script');
    script.src = 'https://widget.timesaverbot.com/embed.js';
    script.setAttribute('data-tenant-id', 'qa');
    script.setAttribute('data-channel-id', '5');
    script.async = true;
    document.body.appendChild(script);
})();

Browser Support

The widget supports the following browsers:

Security

Isolation via Iframe

The widget uses iframe with sandbox attributes for security:

• allow-scripts - allows JavaScript execution
• allow-same-origin - allows same-origin requests
• allow-forms - allows forms
• allow-popups - allows popups

Origin Validation

All messages between parent page and iframe are verified against allowed origins.

Recommendations

1. Use HTTPS for loading the widget
2. Don't pass sensitive data through data-attributes
3. Use authentication tokens for protected data
4. Regularly update widget URL to latest version

Additional Information

Widget Dimensions

• Closed state: 60x60 pixels (round button)
• Open state: 500x600 pixels (on desktop)
• Mobile devices: Adapts to screen size

Performance

The widget loads asynchronously and doesn't block page rendering. Using iframe ensures isolation and doesn't affect main site performance.

Customization

The widget supports customization through theme, position, and language parameters, as well as through server-side settings (see Server-Side Customization Settings).