Custom Buttons & Programmatic Control

The chat widget supports multiple ways to open and control it programmatically, allowing you to integrate it seamlessly with your website's design and user experience.

Programmatic API

Once the chat widget is loaded, you can control it using JavaScript methods:

Available Methods

// Open the chat widget
WebChat.open();

// Close the chat widget
WebChat.close();

// Toggle the chat widget (open if closed, close if open)
WebChat.toggle();

// Identify the current user (optional but recommended)
WebChat.identify(
  'user_id', // Replace with your user's unique identifier
  {
    platformLabel: 'ACME', // Optional: source / platform label
    email: '[email protected]', // Optional: additional traits
  },
);

Example Usage

// Open chat when user clicks a custom button
document.getElementById('my-help-button').addEventListener('click', function() {
    WebChat.open();
});

// Close chat programmatically
function closeChatWidget() {
    WebChat.close();
}

// Toggle chat state
function toggleChatWidget() {
    WebChat.toggle();
}

Data Attributes

The easiest way to create custom buttons is using the data-open-web-chat attribute. Any element with this attribute will automatically open the chat when clicked.

Basic Usage

<!-- Button that opens the chat -->
<button data-open-web-chat>Contact Support</button>

<!-- Link that opens the chat -->
<a href="#" data-open-web-chat>Get Help</a>

<!-- Any element can be used -->
<div data-open-web-chat class="custom-help-card">
    <h3>Need Help?</h3>
    <p>Click here to start a conversation</p>
</div>

ID-based Control

You can also use a specific element ID to control the chat:

<!-- Element with specific ID -->
<a href="#" id="open-web-chat">Contact Support</a>

<!-- This will automatically open the chat when clicked -->
<button id="open-web-chat" type="button">
    Get Help Now
</button>

Dynamic Elements

The widget automatically detects elements added to the page after it loads, so you can safely add custom buttons dynamically:

// Dynamically add a custom button that will work automatically
function addHelpButton() {
    const button = document.createElement('button');
    button.setAttribute('data-open-web-chat', '');
    button.textContent = 'Need Help?';
    button.className = 'help-button';
    
    document.body.appendChild(button);
    // The button will automatically work - no additional setup needed!
}

// Add button after page loads
setTimeout(addHelpButton, 2000);

Implementation Examples

E-commerce Product Page

<div class="product-details">
    <h1>Amazing Product</h1>
    <p class="price">$99.99</p>
    
    <div class="action-buttons">
        <button class="btn-primary">Add to Cart</button>
        <button class="btn-secondary" data-open-web-chat>
            Ask a Question
        </button>
    </div>
</div>

Help Section

<section class="help-section">
    <h2>Need Help?</h2>
    <div class="help-options">
        <div class="help-option">
            <h3>📚 Documentation</h3>
            <p>Browse our comprehensive guides</p>
            <a href="/docs" class="btn">View Docs</a>
        </div>
        
        <div class="help-option" data-open-web-chat>
            <h3>💬 Live Chat</h3>
            <p>Get instant help from our team</p>
            <button class="btn">Start Chat</button>
        </div>
        
        <div class="help-option">
            <h3>📧 Email Support</h3>
            <p>Send us a detailed message</p>
            <a href="mailto:[email protected]" class="btn">Send Email</a>
        </div>
    </div>
</section>

Best Practices

1. Accessibility

Ensure your custom buttons are accessible:

<button 
    data-open-web-chat 
    aria-label="Open chat support"
    role="button"
    tabindex="0"
>
    💬 Support
</button>

2. Visual Feedback

Provide clear visual feedback:

[data-open-web-chat] {
    cursor: pointer;
    transition: all 0.2s ease;
}

[data-open-web-chat]:hover {
    opacity: 0.8;
    transform: translateY(-1px);
}

[data-open-web-chat]:active {
    transform: translateY(0);
}

3. Positioning

Consider the chat widget's position when placing custom buttons:

<!-- Good: Button positioned away from widget -->
<button 
    data-open-web-chat 
    style="position: fixed; top: 20px; right: 20px;"
>
    Quick Support
</button>

<!-- Avoid: Button too close to widget position -->
<button 
    data-open-web-chat 
    style="position: fixed; bottom: 20px; right: 20px;"
>
    Support
</button>

4. Context-Aware Buttons

Create buttons that are relevant to the current page:

<!-- On pricing page -->
<div class="pricing-card">
    <h3>Pro Plan</h3>
    <p class="price">$29/month</p>
    <button class="btn-primary">Choose Plan</button>
    <button class="btn-link" data-open-web-chat>
        Questions about Pro features?
    </button>
</div>

<!-- On product page -->
<div class="product-info">
    <h1>Product Name</h1>
    <button class="btn-primary">Add to Cart</button>
    <button class="btn-secondary" data-open-web-chat>
        Need help choosing?
    </button>
</div>

Troubleshooting

Button Not Working

If your custom button isn't opening the chat:

1. Check the attribute: Ensure you're using data-open-web-chat (not data-open-webchat)
2. Verify widget loading: Make sure the chat widget script has loaded completely
3. Check console: Look for JavaScript errors in your browser's developer console
4. Test programmatically: Try WebChat.open() in the console to verify the widget is ready

Widget Not Responding

If the programmatic API isn't working:

1. Wait for load: Ensure the widget is fully loaded before calling methods
2. Check availability: Verify WebChat object exists: console.log(WebChat)
3. Timing issues: If calling immediately, wrap in a timeout or check for widget readiness

// Wait for widget to be ready
function waitForWidget(callback) {
    if (window.WebChat && window.WebChat.open) {
        callback();
    } else {
        setTimeout(() => waitForWidget(callback), 100);
    }
}

waitForWidget(() => {
    WebChat.open();
});