Widget Integration Guide

The Synaplan inline chat widget allows you to embed an AI-powered chat interface directly into your website. This guide covers installation, configuration, and JavaScript API usage.

Quick Start

Add this script tag to your website:

<!-- Synaplan Chat Inline Box -->
<script src="https://app.synaplan.com/widget.php?uid=YOUR_USER_ID&widgetid=YOUR_WIDGET_ID&mode=inline-box"></script>

Replace YOUR_USER_ID and YOUR_WIDGET_ID with your actual credentials from the Synaplan dashboard.

Features

  • 🎨 Brand Colors: Automatically matches your brand with customizable colors
  • 📎 File Upload: Built-in support for PDFs, Word documents, images
  • ⌨️ Keyboard Navigation: Full accessibility support
  • 📱 Responsive Design: Works seamlessly on desktop, tablet, and mobile
  • ✨ Animation Support: Animated text typing effects
  • 🔧 JavaScript API: Full programmatic control

Widget Types

Inline Box (Recommended)

The inline box integrates seamlessly into your page layout:

<script src="https://app.synaplan.com/widget.php?uid=2&widgetid=3&mode=inline-box"></script>

Floating Button

A floating button appears in the corner of your page:

<script>
(function() {
    var script = document.createElement('script');
    script.src = 'https://app.synaplan.com/widget.php?uid=2&widgetid=1';
    script.async = true;
    document.head.appendChild(script);
})();
</script>

Configuration

Configure your widget in the Synaplan dashboard under Tools → Web Widget:

  • Primary Color: Main button color
  • Icon Color: Icon inside the button
  • Position: Bottom-right, bottom-left, or bottom-center
  • Auto Message: First message shown to visitors
  • Auto-open: Automatically open after page load
  • AI Prompt: Select which AI persona to use

JavaScript API

The widget exposes a global JavaScript API for advanced control:

Basic Methods

// Set text instantly
SynaplanWidget.setText('Hello!');

// Get current text
var text = SynaplanWidget.getText();

// Clear input
SynaplanWidget.clear();

// Focus input
SynaplanWidget.focus();

Animation Methods

// Animate typing (speed in milliseconds per character)
SynaplanWidget.typeText('How can I help you?', 80);

// Stop any ongoing typing animation
SynaplanWidget.stopTyping();

// Cycle through suggestions (properly managed)
const suggestions = [
    'What is AI?',
    'How does ML work?',
    'Explain neural networks'
];

let index = 0;
setInterval(() => {
    // typeText automatically stops previous animations
    SynaplanWidget.typeText(suggestions[index], 60);
    index = (index + 1) % suggestions.length;
}, 5000);

Note: typeText() automatically clears any previous typing animation before starting a new one, preventing text corruption from overlapping animations.

Control Methods

// Open the chat overlay
SynaplanWidget.open();

// Close the chat overlay
SynaplanWidget.close();

// Check if open
if (SynaplanWidget.isOpen()) {
    console.log('Chat is open!');
}

Styling Methods

// Style the input field
SynaplanWidget.styleInput({
    fontSize: '22px',
    color: '#061c3e',
    fontWeight: 'bold'
});

// Style the button
SynaplanWidget.styleButton({
    background: 'linear-gradient(135deg, #00E5FF, #00FF9D)',
    color: 'white'
});

// Style the container
SynaplanWidget.styleContainer({
    maxWidth: '1000px',
    padding: '30px'
});

Direct DOM Access

// Get DOM elements for advanced manipulation
const input = SynaplanWidget.getInput();
const button = SynaplanWidget.getButton();
const uploadBtn = SynaplanWidget.getUploadButton();

// Add custom event listeners
input.addEventListener('keyup', (e) => {
    console.log('User typed:', e.target.value);
});

// Use with animation libraries (GSAP, anime.js, etc.)
anime({
    targets: input,
    scale: 1.1,
    duration: 500
});

Multiple Widgets

If you have multiple widgets on the same page:

// Access by widget ID
SynaplanInlineWidget[1].setText('Widget 1');
SynaplanInlineWidget[2].setText('Widget 2');
SynaplanInlineWidget[3].setText('Widget 3');

// Or use the shorthand for the first widget
SynaplanWidget.setText('Hello!');

Complete Example

Here's a complete example with cycling suggestions:

<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
</head>
<body>
    <h1>Welcome to My Website</h1>
    
    <!-- Widget -->
    <script src="https://app.synaplan.com/widget.php?uid=2&widgetid=3&mode=inline-box"></script>
    
    <!-- Animation Script -->
    <script>
    setTimeout(() => {
        if (window.SynaplanWidget) {
            const questions = [
                'What services do you offer?',
                'How can I get started?',
                'Tell me about pricing',
                'Do you offer support?'
            ];
            
            let index = 0;
            SynaplanWidget.typeText(questions[0], 70);
            
            setInterval(() => {
                index = (index + 1) % questions.length;
                SynaplanWidget.typeText(questions[index], 70);
            }, 6000);
        }
    }, 500);
    </script>
</body>
</html>

Interactive Demos

File Upload Support

The widget supports uploading files:

  • Documents: PDF, Word (.doc, .docx), Excel, PowerPoint
  • Images: JPG, PNG, GIF, WebP
  • Text: Plain text, Markdown, CSV
  • Code: Most programming languages

Click the paperclip icon 📎 in the widget to upload files.

Z-Index & Overlay Behavior

The widget overlay is designed to always appear on top of your website content:

  • Uses maximum z-index value (2147483647)
  • Enforced with !important flags
  • Additional CSS injection for compatibility
  • Works across all external domains
  • Won't be covered by sticky headers or navigation

This ensures the chat modal is always accessible to users, regardless of your website's CSS.

Mobile Responsiveness

The widget is fully responsive and adapts to different screen sizes:

Desktop & Tablet (768px and above)

  • Horizontal layout (input and button side-by-side)
  • Large button on the right (prominent call-to-action)
  • Button auto-width (sized to content)
  • Full padding: 20px/40px button, 20px/28px input
  • Font size: 18px (configurable)
  • Max-width: 900px (centered)
  • Spacious, professional appearance

Mobile (below 768px)

  • Vertical/stacked layout (input above button)
  • Button full-width (100% width for easy tapping)
  • Reduced padding: 14px vertical, 16px horizontal
  • Smaller fonts: 15px
  • Smaller upload icon (18×18px)
  • Optimized for thumb-friendly interaction
  • Compact design for small screens

Viewport Meta Tag

Ensure your page includes this meta tag for proper mobile rendering:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Browser Compatibility

The widget works in all modern browsers:

  • ✅ Chrome/Edge 90+
  • ✅ Firefox 88+
  • ✅ Safari 14+
  • ✅ Mobile browsers (iOS Safari, Chrome Mobile)
  • ✅ Responsive design (mobile-first)

Security & Privacy

  • All data is encrypted in transit (HTTPS)
  • Session cookies are secure with SameSite=None
  • No data is stored in localStorage
  • Files are scanned for security
  • Rate limiting prevents abuse

Troubleshooting

Widget Not Appearing

  1. Check that the script URL is correct
  2. Verify your User ID and Widget ID
  3. Check browser console for errors
  4. Ensure JavaScript is enabled

API Not Working

  1. Wait 500ms after page load for widget to initialize
  2. Check that window.SynaplanWidget exists
  3. Use browser DevTools to debug

Styling Issues

The widget uses inline styles with !important to prevent conflicts. If you need to override:

// Use the styling API
SynaplanWidget.styleInput({
    fontSize: '24px !important'
});

Support

Next Steps