Advanced features, customizations, and integrations for power users.
The widget exposes a global CompaninWidget object for programmatic control. This allows you to integrate the widget deeply into your application's user experience, triggering widget actions based on user behavior or application state.
The API is loaded asynchronously, so always check if it exists before calling methods. You can also listen for a custom event when it's ready.
These methods give you full programmatic control over the widget's visibility and behavior.
<script id="companin-widget-script-sales" src="https://widget.companin.tech/widget.js" data-client-id="YOUR_CLIENT_ID" data-assistant-id="YOUR_ASSISTANT_ID" data-config-id="YOUR_CONFIG_ID" data-instance-id="sales-widget"></script><script> // Ensure the widget has loaded before calling methods window.addEventListener('load', () => { const salesWidget = window.CompaninWidgets?.get('sales-widget') || window.CompaninWidget; if (salesWidget) { salesWidget.show(); salesWidget.sendMessage && salesWidget.sendMessage('Hello from page'); } });</script>Listen for widget events using the postMessage API. This is perfect for tracking user engagement, triggering application logic based on widget interactions, or syncing widget state with your application.
Common use cases:
<script>window.addEventListener('message', (event) => { if (event.origin !== 'https://widget.companin.tech') return; const { type, data } = event.data || {}; switch (type) { case 'WIDGET_READY': console.log('Widget is ready'); break; case 'WIDGET_OPENED': console.log('Widget was opened'); break; case 'MESSAGE_SENT': console.log('User sent message:', data?.message); break; }});</script>While the configuration interface provides extensive styling options, you can go even further with custom CSS for advanced customizations. This is useful when you need unique visual effects, animations, or styles that aren't available in the standard configuration.
Important considerations:
!important sparingly—only when necessary to override iframe isolationTarget widget elements using the container class. Add your custom CSS either in the widget configuration's custom CSS field or in your site's global stylesheet:
/* Target the widget container */.companin-widget-container { /* Custom styles */}/* Style the collapsed button */.companin-widget-container button { border-radius: 50% !important; box-shadow: 0 0 20px rgba(0, 0, 0, 0.3) !important;}/* Custom message bubble styles */.companin-widget-container .message-bubble { background: linear-gradient(45deg, #667eea 0%, #764ba2 100%) !important;}/* Hide the default close button */.companin-widget-container .close-button { display: none !important;}Advanced theming with CSS custom properties:
:root { /* Override widget theme variables */ --companin-primary: #ff6b6b; --companin-secondary: #4ecdc4; --companin-background: #2d3748; --companin-text: #e2e8f0; --companin-border-radius: 12px;}/* Dark theme variant */@media (prefers-color-scheme: dark) { :root { --companin-background: #1a202c; --companin-text: #f7fafc; }}Understanding how users interact with your widget is crucial for optimization. By integrating with your analytics platform, you can track engagement metrics, identify popular topics, and measure the widget's impact on user experience and conversion rates.
Key metrics to track:
Track widget interactions as custom events in Google Analytics. This integrates seamlessly with your existing analytics setup:
// Track widget eventswindow.addEventListener('message', (event) => { if (event.origin !== 'https://widget.companin.tech') return; const { type, data } = event.data; switch (type) { case 'WIDGET_OPENED': gtag('event', 'widget_opened', { event_category: 'engagement', event_label: 'chat_widget' }); break; case 'MESSAGE_SENT': gtag('event', 'message_sent', { event_category: 'engagement', event_label: data.messageLength > 50 ? 'long_message' : 'short_message' }); break; case 'CONVERSATION_STARTED': gtag('event', 'conversation_started', { event_category: 'engagement', event_label: 'chat_widget' }); break; }});// Custom analytics trackingconst trackWidgetEvent = (eventName, properties = {}) => { fetch('/api/analytics/track', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ event: eventName, properties: { widget: 'companin', ...properties } }) });};window.addEventListener('message', (event) => { if (event.origin !== 'https://widget.companin.tech') return; const { type, data } = event.data; switch (type) { case 'WIDGET_OPENED': trackWidgetEvent('widget_opened'); break; case 'MESSAGE_SENT': trackWidgetEvent('message_sent', { length: data.message?.length || 0 }); break; }});Webhooks provide real-time notifications when events occur in the widget. This enables powerful integrations with your backend systems, CRM, helpdesk software, or custom workflows.
Webhook benefits:
Configure webhook URLs in your dashboard to receive HTTP POST requests when specific events occur. Each webhook payload includes event data and metadata:
{ "event": "message_received", "timestamp": "2024-01-09T10:30:00Z", "data": { "session_id": "sess_123456", "message": { "id": "msg_789", "content": "Hello, I need help", "sender": "user", "timestamp": "2024-01-09T10:30:00Z" }, "metadata": { "user_agent": "Mozilla/5.0...", "ip_address": "192.168.1.1", "locale": "en" } }}widget_opened - User opened the widgetwidget_closed - User closed the widgetconversation_started - New conversation initiatedmessage_received - User sent a messagemessage_sent - Assistant sent a messageflow_triggered - Conversation flow was activatedsession_ended - Conversation session endedSecurity is paramount when embedding third-party content on your website. While the widget follows security best practices, there are additional steps you can take to harden your integration.
Content Security Policy headers help prevent XSS attacks and other code injection vulnerabilities. Configure your CSP to explicitly allow the widget while maintaining strict security elsewhere:
# nginx.confadd_header Content-Security-Policy " default-src 'self'; script-src 'self' https://widget.companin.tech; style-src 'self' 'unsafe-inline' https://widget.companin.tech; frame-src https://widget.companin.tech; connect-src 'self' https://app.companin.tech;" always;Always validate and sanitize user inputs:
// Validate message contentfunction validateMessage(message) { if (message.length > 2000) { return { valid: false, error: 'Message too long' }; } const dangerousPatterns = [/<script/i, /javascript:/i, /onw+s*=/i]; for (const pattern of dangerousPatterns) { if (pattern.test(message)) { return { valid: false, error: 'Invalid content' }; } } return { valid: true };}const validation = validateMessage(userInput);if (!validation.valid) { showError(validation.error); return;}The widget is optimized for performance out of the box, but there are strategies to make it even faster and more efficient, especially on high-traffic sites or slower connections.
Instead of loading the widget immediately when the page loads, defer it until the user needs it or after critical content has loaded. This improves your page's initial load time and Core Web Vitals scores:
// Load widget only when neededfunction loadWidget() { if (window.CompaninWidget) return; // Already loaded const script = document.createElement('script'); script.src = 'https://widget.companin.tech/widget.js'; script.setAttribute('data-client-id', 'YOUR_CLIENT_ID'); script.setAttribute('data-assistant-id', 'YOUR_ASSISTANT_ID'); script.setAttribute('data-config-id', 'YOUR_CONFIG_ID'); document.head.appendChild(script);}// Load on user interactiondocument.addEventListener('click', () => { loadWidget();}, { once: true });// Or load after page loadwindow.addEventListener('load', () => { setTimeout(loadWidget, 2000);});Ensure your color choices meet WCAG guidelines: