Widget Controls

Widget Controls Overview

The Chatislav SDK provides programmatic control over your AI Agent widgets. Control widgets individually by their instance ID or manage all widgets at once.

 

Opening and Closing Widgets

Open Widget:

// Open all widgets
window.chatislav.open();

// Open specific widget by instance ID
window.chatislav.open('ctslv_bbl');

Close Widget:

// Close all widgets
window.chatislav.close();

// Close specific widget by instance ID
window.chatislav.close('ctslv_bbl');

Practical Examples:

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

// Close chat when user completes a form
document.getElementById('contact-form').addEventListener('submit', function() {
  window.chatislav.close('support-chat');
});

 

Send User Messages Programmatically

Send user messages to widgets programmatically. This function simulates a user typing and sending a message:

// Send user message to all widgets
window.chatislav.send_message('Hello, I need help with my order');

// Send user message to specific widget by instance ID
window.chatislav.send_message('I have a technical question', 'tech-support');

Practical Examples:

// Send user message based on button click
document.getElementById('pricing-help').addEventListener('click', function() {
  window.chatislav.send_message('I have questions about your pricing plans', 'sales-widget');
  window.chatislav.open('sales-widget');
});

// Send user message with form data when user clicks help button
document.getElementById('form-help').addEventListener('click', function() {
  const formData = getFormData();
  window.chatislav.send_message(`I need help with this form: ${formData}`, 'main-chat');
  window.chatislav.open('main-chat');
});

// Send user question from quick question form
document.getElementById('quick-question').addEventListener('submit', function(e) {
  e.preventDefault();
  const question = document.getElementById('question-input').value;
  window.chatislav.send_message(question, 'main-chat');
  window.chatislav.open('main-chat');
});

 

Dynamic Configuration Updates

Update widget settings in real-time without requiring a page reload:

window.chatislav.update_config({
  config: {
    main_color: '#ff6b35',
    welcome_message: 'Hi! How can I assist you today?',
    input_placeholder: 'Type your message here...'
  }
}, 'ctslv_bbl');

Complete Configuration Update:

window.chatislav.update_config({
  base_url: 'https://api.chatislav.com',
  token: 'your-widget-token',
  config: {
    main_color: '#2563eb',
    welcome_message: 'Welcome! I\'m here to help.',
    input_placeholder: 'Type your message here...',
    chatislav_branding: false,
    position: 'bottom-right'
  }
}, 'customer-support');

Update All Widgets:

// Update all widgets (omit instance_id parameter)
window.chatislav.update_config({
  config: {
    main_color: '#10b981',
    welcome_message: 'Updated message for all widgets'
  }
});

 

User Session Management

Set user identification and context for personalized experiences. For detailed information about user session configuration, see User Session Identity.

Set User Session for All Widgets:

window.chatislav.user_session({
  user_id: "user-12345",
  user_id_hash: "generated-hmac-hash",
  user_metadata: {
    name: "John Doe",
    email: "john@example.com",
    plan: "premium"
  }
});

Set User Session for Specific Widget:

window.chatislav.user_session({
  user_id: "user-12345",
  user_id_hash: "generated-hmac-hash", 
  user_metadata: {
    department: "sales",
    current_page: "/products/enterprise"
  }
}, 'sales-widget');

 

Multiple Widget Management

Control multiple widgets individually or collectively:

HTML Setup:

<script>
  // Initialize first widget with instance ID 'sales-chat'
  (function (w, d, o, f) {
    w[o] = w[o] || function (config) {
      var js = d.createElement("script");
      js.src = f;
      js.async = true;
      js.onload = function () {
        var e = d.createElement("div");
        e.id = o;
        d.body.appendChild(e);
        w.init_chatislav ? w.init_chatislav(o, config) : console.error("chatislav init function not available.");
      };
      d.body.appendChild(js);
    };
  })(window, document, "sales-chat", "https://chatislav.ai/api/static/chat-bot/index.js");
  
  sales_chat({ 
    base_url: "https://chatislav.ai/api", 
    token: "sales-token",
    config: { main_color: '#10b981' }
  });

  // Initialize second widget with instance ID 'tech-support'
  (function (w, d, o, f) {
    w[o] = w[o] || function (config) {
      var js = d.createElement("script");
      js.src = f;
      js.async = true;
      js.onload = function () {
        var e = d.createElement("div");
        e.id = o;
        d.body.appendChild(e);
        w.init_chatislav ? w.init_chatislav(o, config) : console.error("chatislav init function not available.");
      };
      d.body.appendChild(js);
    };
  })(window, document, "tech-support", "https://chatislav.ai/api/static/chat-bot/index.js");
  
  tech_support({ 
    base_url: "https://chatislav.ai/api", 
    token: "tech-token",
    config: { main_color: '#3b82f6' }
  });
</script>

Controlling Multiple Widgets:

// Open specific widget based on user selection
function openSupportChat(type) {
  window.chatislav.close(); // Close all others first
  
  switch(type) {
    case 'sales':
      window.chatislav.open('sales-chat');
      break;
    case 'technical':
      window.chatislav.open('tech-support');
      break;
  }
}

// Update all widgets with new branding
function updateBranding(newColors) {
  window.chatislav.update_config({
    config: { main_color: newColors.primary }
  });
}

// Update specific widgets individually
function updateSpecificWidgets(newColors) {
  ['sales-chat', 'tech-support'].forEach(instanceId => {
    window.chatislav.update_config({
      config: { main_color: newColors.primary }
    }, instanceId);
  });
}

 

Understanding Instance IDs

The instance ID is the identifier you provide when deploying the script. In this example:

<script>
  (function (w, d, o, f) {
    w[o] = w[o] || function (config) {
      var js = d.createElement("script");
      js.src = f;
      js.async = true;
      js.onload = function () {
        var e = d.createElement("div");
        e.id = o;
        d.body.appendChild(e);
        w.init_chatislav ? w.init_chatislav(o, config) : console.error("chatislav init function not available.");
      };
      d.body.appendChild(js);
    };
  })(window, document, "ctslv_bbl", "https://chatislav.ai/api/static/chat-bot/index.js");
  
  ctslv_bbl({ 
    base_url: "https://chatislav.ai/api", 
    token: "your-widget-token" 
  });
</script>

"ctslv_bbl" is the instance ID that you use to control this specific widget.

 

Contextual Widget Behavior

Page-Specific Configuration:

function configureWidgetForPage() {
  const currentPage = window.location.pathname;
  let config = {};
  
  if (currentPage.includes('/pricing')) {
    config = {
      config: {
        welcome_message: 'Questions about our pricing?',
        main_color: '#059669'
      }
    };
  } else if (currentPage.includes('/support')) {
    config = {
      config: {
        welcome_message: 'Welcome to support!',
        main_color: '#dc2626'
      }
    };
  }
  
  if (Object.keys(config).length > 0) {
    window.chatislav.update_config(config, 'main-widget');
  }
}

User Behavior Responsive Widget:

// Show widget after 30 seconds
setTimeout(() => {
  window.chatislav.open('engagement-widget');
}, 30000);

// Show widget on scroll to bottom
let hasTriggered = false;
window.addEventListener('scroll', () => {
  if (!hasTriggered && 
      (window.innerHeight + window.scrollY) >= document.body.offsetHeight - 100) {
    window.chatislav.open('exit-intent-widget');
    hasTriggered = true;
  }
});

// Open widget when user attempts to leave (exit intent)
document.addEventListener('mouseleave', function() {
  window.chatislav.open('retention-widget');
});

 

Instance Management & Conversation Access

Inspect and manage widget instances, and read the current conversation, at runtime.

List and check instances:

// Get an array of all active widget instance IDs
const ids = window.chatislav.get_instance_ids();

// Check whether a specific instance exists
if (window.chatislav.has_instance('sales-widget')) {
  window.chatislav.open('sales-widget');
}

// Get the current configuration of an instance
const config = window.chatislav.get_instance_config('sales-widget');

Read the conversation:

// Get the messages of the current conversation (optionally for a specific instance)
const messages = window.chatislav.get_messages('main-chat');
messages.forEach(m => console.log(m.role, m.content));

Destroy an instance:

// Remove a widget instance from the page and clean it up
window.chatislav.destroy_instance('sales-widget');

 

Voice Widget Controls

Coming Soon

Integration Examples

E-commerce Integration:

function updateWidgetForCart() {
  const cartItems = getCartItemCount();
  
  if (cartItems === 0) {
    window.chatislav.update_config({
      config: {
        welcome_message: 'Looking for something specific?',
        bot_name: 'Product Finder'
      }
    }, 'shopping-assistant');
  } else {
    window.chatislav.update_config({
      config: {
        welcome_message: `You have ${cartItems} items. Need help with checkout?`,
        bot_name: 'Checkout Assistant'
      }
    }, 'shopping-assistant');
  }
}

Authentication Integration:

function handleUserLogin(userData) {
  window.chatislav.user_session({
    user_id: userData.id,
    user_id_hash: userData.hash,
    user_metadata: {
      name: userData.name,
      membership_level: userData.membership
    }
  });
  
  window.chatislav.update_config({
    config: {
      welcome_message: `Welcome back, ${userData.name}!`
    }
  }, 'main-chat');
}

Form Integration:

// Only send user message when user explicitly requests help with form
document.getElementById('form-help-button').addEventListener('click', function() {
  const formData = getCurrentFormData();
  const message = `I need help with this form: ${JSON.stringify(formData)}`;
  window.chatislav.send_message(message, 'form-support');
  window.chatislav.open('form-support');
});

 

Best Practices

1. Use Descriptive Instance IDs - Choose meaningful names like 'sales-widget' or 'tech-support'
2. Coordinate Multiple Widgets - Ensure widgets don't interfere with each other
3. Update Configuration Sparingly - Frequent updates can be jarring to users
4. Handle Errors Gracefully - Check if widgets exist before controlling them
5. Test Across Devices - Ensure controls work on desktop and mobile
6. Respect User Preferences - Don't force widgets open if users closed them