Widget Integration

The Synaplan Chat Widget is a modern ES module that adds AI-powered chat to any website with a single <script> tag.

Quick Embed

Add this to your page before the closing </body> tag:

<script type="module">
  import SynaplanWidget from 'https://web.synaplan.com/widget.js'

  SynaplanWidget.init({
    widgetId: 'YOUR_WIDGET_ID'
  })
</script>

Replace YOUR_WIDGET_ID with the widget ID from the Synaplan dashboard (e.g. wdg_095ab093...). The widget will appear as a floating chat button in the bottom-right corner.

Complete Example

<script type="module">
  import SynaplanWidget from 'https://web.synaplan.com/widget.js'

  SynaplanWidget.init({
    widgetId: 'wdg_095ab093966991158f9957f42ae8b4f2',
    position: 'bottom-right',
    primaryColor: '#13224e',
    iconColor: '#ffffff',
    defaultTheme: 'light',
    autoOpen: false,
    autoMessage: 'Hi! How can I help you today?',
    messageLimit: 50,
    maxFileSize: 10,
    allowFileUpload: false,
    fileUploadLimit: 3,
    lazy: true,
    buttonIconUrl: 'https://web.synaplan.com/api/v1/files/uploads/widget-icons/02/000/00002/2026/03/wicon_example.svg'
  })
</script>

Configuration Options

Option Type Default Description
widgetId string required Widget ID from the dashboard (e.g. wdg_...)
position string 'bottom-right' Button position: bottom-right, bottom-left, top-right, top-left
primaryColor string '#007bff' Primary brand color (hex)
iconColor string '#ffffff' Icon color on the button (hex)
buttonIcon string 'chat' Built-in icon: chat, headset, help, robot, message, support
buttonIconUrl string — Custom icon URL (overrides buttonIcon)
defaultTheme string 'light' light or dark
detectTheme boolean false Auto-detect host page theme
autoOpen boolean false Open chat automatically on page load
autoMessage string 'Hello! How can I help you today?' Initial greeting message
widgetTitle string 'Chat Support' Title shown in chat header
messageLimit number 50 Maximum messages per session
allowFileUpload boolean false Enable file uploads
fileUploadLimit number 3 Max files per message
maxFileSize number 10 Max file size in MB
lazy boolean true Lazy-load Vue and chat UI on first interaction
fullscreenMode boolean false Start in fullscreen mode
allowFullscreen boolean false Allow users to toggle fullscreen
hideButton boolean false Hide the floating button (control via API only)
apiUrl string auto-detected Override the API base URL (auto-detected from script source)
externalUserId string — External user ID for authenticated sessions
privacyPolicyUrl string — Link to your privacy policy
allowedDomains string[] [] Restrict widget to specific domains

JavaScript API

After calling init(), the widget exposes these methods:

import SynaplanWidget from 'https://web.synaplan.com/widget.js'

// Initialize the widget
SynaplanWidget.init({ widgetId: 'wdg_...' })

// Open the chat panel programmatically
SynaplanWidget.open()

// Close the chat panel
SynaplanWidget.close()

// Start a new chat conversation
SynaplanWidget.startNewChat()

// Tear down the widget completely (removes all DOM elements)
SynaplanWidget.destroy()

How it Works

  • ES Modules: Built as a modern ES module with Vite, supporting automatic code-splitting.
  • Lazy Loading: With lazy: true (default), Vue and the chat UI are only loaded when the user first clicks the button.
  • Auto API Detection: The widget detects the correct API URL from import.meta.url, so no manual configuration is needed.
  • Remote Config: The widget fetches additional settings from the server (/api/v1/widget/{widgetId}/config), allowing dashboard changes to take effect without re-deploying embed code.
  • Cross-Origin Ready: Works on any domain with full CORS support.

File Upload Support

When allowFileUpload is enabled, users can upload:

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

Local Development & Testing

  1. Start your local Synaplan instance: docker compose up -d
  2. Build the widget: make -C frontend build:widget
  3. Open http://localhost:8000/widget-test.html in your browser

Custom UI with the API

If you prefer to build your own chat interface instead of using the widget, you can use the Messages API directly:

  1. Authenticate: Use an API key (X-API-Key header) or call /api/v1/auth/me.
  2. Send Message: POST /api/v1/messages with your message content.
  3. Stream Response: Connect to /api/v1/messages/stream?token=... via SSE.

Troubleshooting

Widget Not Appearing

  1. Check that widgetId matches a valid widget in your dashboard
  2. Verify type="module" is set on the script tag
  3. Check browser console for errors (CORS, 404, etc.)
  4. Ensure the widget domain is allowed in allowedDomains if configured

Browser Compatibility

ES module widgets require modern browsers: Chrome/Edge 90+, Firefox 88+, Safari 14+.

Support