Dashboard Widget

Overview

The Botsplash Dashboard widget allows customers to embed the full Botsplash dashboard directly into their CRM or agent applications as an iframe widget. This enables agents to engage with customers without leaving their primary work environment.

⚠️ Important Security Requirements

DOMAIN WHITELISTING IS REQUIRED: Before implementing the widget, your domain must be whitelisted by Botsplash for security reasons. Contact Botsplash support to whitelist your CRM domain.

Pre-whitelisted Domains

The following CRM platforms are already whitelisted and require no action:

Salesforce
HubSpot
Other major CRM platforms (contact support for confirmation)

X-Frame-Options Error

If you encounter an error message containing X-Frame-Options directive set to "sameorigin", this indicates your domain is not whitelisted. Please contact Botsplash support with your updated domain to resolve this issue.

Basic Implementation

Add the following JavaScript code to your CRM website or application:

// Set your Botsplash account URL
window.BSPDASHBOARD_APP_URL = "https://<account-id>.botsplash.com";

// Load the dashboard widget script
(function () {
    d = document;
    s = d.createElement("script");
    s.src = "https://<account-id>.botsplash.com/y.js";
    s.async = true;
    d.getElementsByTagName("head")[0].appendChild(s);
})();

Important: Replace <account-id> with your actual Botsplash account ID.

Step 2: Load Specific Visitors (Optional)

To automatically load a specific visitor’s conversation in the widget:

$bspdashboard.loadVisitor({
    clientVisitorId: 'CRM_CUSTOMER_ID'
});

This functionality is particularly useful for:

Auto-loading visitor data based on incoming phone calls
Displaying customer information when clicking on customer records
Context-aware customer engagement

Authentication

SSO Authentication (Default)

By default, SSO (Single Sign-On) login is required for accessing the dashboard widget. Users will need to authenticate through your configured SSO provider before accessing the dashboard.

Implicit Authentication (Alternative)

If SSO login is not preferred for your use case, contact Botsplash support to discuss implementing implicit authentication. This alternative authentication method requires:

Code changes on Botsplash’s end to facilitate the authentication integration
Coordination with the Botsplash development team to implement custom authentication flow
Security review to ensure the implicit authentication meets your security requirements

Note: Implementing implicit authentication is a custom integration that requires development work from the Botsplash team. Contact support early in your planning process to discuss feasibility, timeline, and any additional requirements.

Advanced Implementation Examples

Example 1: Complete jQuery Implementation

$(document).ready(function () {
    // Initialize Botsplash Dashboard Widget
    window.BSPDASHBOARD_APP_URL = 'https://abc.botsplash.com';

    (function () {
        d = document;
        s = d.createElement("script");
        s.src = "https://abc.botsplash.com/y.js";
        s.async = true;
        d.getElementsByTagName("head")[0].appendChild(s);
    })();

    // Click handler for phone numbers
    $('.divPhone').on('click', function () {
        var clientAppId = $(this).parents('.mstn26').find('.loanNr').val();

        if ($bspdashboard && clientAppId) {
            $bspdashboard.loadVisitor({
                clientAppId: clientAppId
            });
        } else {
            console.log('Botsplash -> Client App ID not found');
        }
    }).css({
        'text-decoration': 'underline dotted #1a5b9b',
        'text-underline-offset': '3px'
    });
});

This example demonstrates:

Automatic widget initialization on page load
Click event handling for phone numbers
Visual styling for clickable phone numbers
Error handling when client IDs are missing

Example 2: Vanilla JavaScript Implementation

// Initialize when DOM is ready
document.addEventListener('DOMContentLoaded', function() {
    // Set Botsplash configuration
    window.BSPDASHBOARD_APP_URL = 'https://your-account.botsplash.com';

    // Load widget script
    (function () {
        var d = document;
        var s = d.createElement("script");
        s.src = "https://your-account.botsplash.com/y.js";
        s.async = true;
        d.getElementsByTagName("head")[0].appendChild(s);
    })();

    // Add click handlers for customer records
    document.querySelectorAll('.customer-phone').forEach(function(element) {
        element.addEventListener('click', function() {
            var customerId = this.getAttribute('data-customer-id');

            if (window.$bspdashboard && customerId) {
                window.$bspdashboard.loadVisitor({
                    clientVisitorId: customerId
                });
            }
        });
    });
});

Integration Use Cases

1. Call Center Integration

Automatically load customer conversations when receiving incoming calls:

function handleIncomingCall(phoneNumber, customerId) {
    if (window.$bspdashboard && customerId) {
        window.$bspdashboard.loadVisitor({
            clientVisitorId: customerId
        });
    }
}

2. CRM Record Integration

Load customer conversations when viewing CRM records:

function loadCustomerChat(customerId) {
    if (window.$bspdashboard) {
        window.$bspdashboard.loadVisitor({
            clientVisitorId: customerId
        });
    } else {
        console.warn('Botsplash dashboard widget not loaded');
    }
}

3. Support Ticket Integration

Display related customer conversations in support interfaces:

// When opening a support ticket
function openTicket(ticketId, customerId) {
    // Load ticket details
    loadTicketDetails(ticketId);

    // Load related customer conversations
    if (window.$bspdashboard && customerId) {
        window.$bspdashboard.loadVisitor({
            clientVisitorId: customerId
        });
    }
}

Configuration Options

Required Configuration

window.BSPDASHBOARD_APP_URL: Your Botsplash account URL
Widget script URL: https://<account-id>.botsplash.com/y.js

API Methods

$bspdashboard.loadVisitor(options): Load specific visitor conversation
- options.clientVisitorId: Customer ID from your CRM system
- options.clientAppId: Alternative customer identifier

Troubleshooting

Common Issues

X-Frame-Options Error
- Cause: Domain not whitelisted
- Solution: Contact Botsplash support to whitelist your domain
Widget Not Loading
- Cause: Incorrect account ID or script URL
- Solution: Verify your account ID and script URL
Customer Not Loading
- Cause: Invalid or missing customer ID
- Solution: Ensure customer IDs match between your CRM and Botsplash
Script Loading Issues
- Cause: Network restrictions or CORS policies
- Solution: Check browser console for errors and verify network access

Debug Mode

To enable debug logging, add this before loading the widget:

window.BSPDASHBOARD_DEBUG = true;

Best Practices

1. Error Handling

Always check if the widget is loaded before calling methods:

if (window.$bspdashboard) {
    window.$bspdashboard.loadVisitor({
        clientVisitorId: customerId
    });
} else {
    console.warn('Botsplash widget not yet loaded');
}

2. Performance Optimization

Load the widget asynchronously to avoid blocking page rendering:

s.async = true;  // Always use async loading

3. Customer ID Mapping

Ensure consistent customer ID mapping between your CRM and Botsplash:

// Map CRM customer ID to Botsplash visitor ID
function getCrmCustomerId(botsplashVisitorId) {
    // Implement your ID mapping logic here
    return mappedCustomerId;
}

4. Responsive Design

Consider widget responsiveness in different screen sizes and CRM layouts.

Security Considerations

Domain Whitelisting: Always ensure your domain is whitelisted before deployment
HTTPS Required: The widget requires HTTPS for security
Customer Data: Ensure customer IDs don’t expose sensitive information
Authentication: SSO authentication is required for dashboard access

Support and Contact

For technical support, domain whitelisting requests, or feature questions:

Contact Botsplash support team
Provide your account ID and domain information
Include any error messages or browser console logs

Implicit Authentication Requests

If you need to implement implicit authentication instead of SSO:

Contact Botsplash support early in your planning process
Provide details about your authentication requirements and constraints
Be prepared to discuss security considerations and implementation timeline
Note that this requires custom development work from the Botsplash team

Future Enhancements

Planned Features

SSO bypass options for streamlined authentication
Additional customization options for widget appearance
Enhanced API methods for deeper CRM integration

Stay tuned for updates to this documentation as new features become available.

Botsplash Dashboard Widget Integration Guide