Widget Integration

The Synaplan Chat Widget is a powerful, embeddable component that allows you to provide AI-powered support directly on your website.

Quick Embed

To add the Synaplan widget to your site, include the following script tag before the closing </body> tag:

<script 
  src="https://web.synaplan.com/widget.js" 
  data-synaplan-id="YOUR_WIDGET_ID"
  async>
</script>

Replace YOUR_WIDGET_ID with the ID provided in the Synaplan dashboard under Widgets.

How it Works

  • ES Modules: The widget is built as a modern ES module with automatic code-splitting.
  • Dynamic Loading: It lazily loads only the necessary components when the user interacts with the chat button, keeping your initial page load fast.
  • Zero Configuration: The widget automatically detects the correct API URL from its own script source, so you don't need to configure environment variables.
  • Cross-Origin Ready: Designed to work across different domains with full CORS support.

Advanced Configuration

You can customize the widget's behavior through the dashboard or by passing additional data attributes:

  • data-primary-color: Override the primary brand color (e.g., #007bff).
  • data-initial-message: Set a custom greeting message.
  • data-user-id: Pass an internal user ID for authenticated chat sessions.

Local Development & Testing

When developing locally, you can use the built-in test page to verify your widget implementation:

  1. Start your local Synaplan instance (docker compose up -d).
  2. Open http://localhost:8000/widget-test.html in your browser.

Custom UI with the API

If you prefer to build your own custom chat interface instead of using our pre-built widget, you can use the Messages API:

  1. Initialize Session: Call /api/v1/auth/me or use an API key.
  2. Post Message: POST /api/v1/messages.
  3. Stream Response: Use the SSE endpoint /api/v1/messages/stream?token=....