Soliplex Chat Widget

A React-based embeddable chat widget that connects to a Soliplex/PydanticAI backend using the AG-UI protocol. Supports OIDC authentication via popup flow.

Live Demo

Quick Start

# Install dependencies
npm install

# Start development server
npm run dev

# Build embeddable widget
npm run build:widget

Embedding the Widget

Add to any HTML page:

<script src="https://soliplex.github.io/chatbot/soliplex-chat.js"></script>
<script>
  SoliplexChat.init({
    baseUrl: "https://my-server.example.com",
    title: "Chat with us",
    placeholder: "Ask me anything..."
  });
</script>

If baseUrl is omitted, the widget will prompt the user to enter a server URL:

<script>
  SoliplexChat.init({
    title: "Connect to Chat"
  });
</script>

The widget will:

1. If no baseUrl is configured, show a server URL prompt
2. Check if authentication is required (fetches /api/login)
3. If auth is configured, show a login screen with available providers
4. After authentication (or if no auth required), fetch available rooms from /api/v1/rooms
5. Display a room selector if multiple rooms exist, or auto-select if only one

Configuration Options

Option	Type	Default	Description
baseUrl	string	undefined	Backend API URL. If omitted, the widget prompts the user for a server URL
roomId	string	undefined	Single room ID - skip room selection and go directly to this room (takes precedence over roomIds)
roomIds	string[]	undefined	Optional list of room IDs to show (filters the available rooms)
fallbackRoomIds	string[]	undefined	Room(s) to use when none of the roomIds are accessible to the user, tried in order; the first accessible one wins. Ignored without roomIds
title	string	"Chat with us"	Chat header title
placeholder	string	"Ask me anything..."	Empty state message; overrides the room's welcome message
noRoomsMessage	string	"No rooms available"	Text shown when the user can't access any room (none of roomIds or fallbackRoomIds, or the server returned none). Plain text
bubbleColor	string	Soliplex primary	Accent for the launcher bubble and primary buttons; the icon/label color is picked automatically for contrast
theme	string	"auto"	"light", "dark", or "auto" (follows the visitor's OS setting)
position	string	"bottom-right"	"bottom-right" or "bottom-left"
autoHideSeconds	number	0	Auto-hide delay (0 = never)
tools	array	[]	Custom client-side tools

Note: If roomId is set, the widget will skip the room selector and go directly to the specified room after authentication (if auth is enabled). If none of the configured rooms are accessible to the logged-in user, the widget opens the first accessible room from fallbackRoomIds instead, without a room picker; with no accessible fallback it shows "No rooms available", or the noRoomsMessage text if set.

Authentication

The widget supports OIDC authentication through the Soliplex backend. When auth systems are configured on the backend:

1. The widget fetches available auth providers from /api/login
2. User clicks a provider button to start OAuth flow
3. A popup window opens for authentication (no page redirect)
4. On success, tokens are passed back to the widget via postMessage
5. All subsequent API calls include the Bearer token

Auth Callback Page

For the popup flow to work, the widget bundle includes a callback page (soliplex-auth-callback.html) that must be served from the same origin as the widget. This page captures tokens from URL parameters and sends them to the parent window.

Backend Configuration

Enable OIDC on the backend by creating a config file (e.g., oidc/config.yaml):

oidc_client_pem_path: "./cacert.pem"

auth_systems:
  - id: "keycloak"
    title: "Sign in with Keycloak"
    server_url: "https://your-keycloak.example.com/realms/your-realm"
    client_id: "your-client-id"
    client_secret: "your-client-secret"
    scope: "openid email profile"
    token_validation_pem: |
        -----BEGIN PUBLIC KEY-----
        ...your public key...
        -----END PUBLIC KEY-----

Development with Docker

For local testing with the nginx proxy (handles CORS and auth redirects):

docker compose up

This starts:

• soliplex_backend on port 8000
• chatbot_widget (nginx) on port 8080 serving the widget files

Access the widget at http://localhost:8080

Documentation

• Development Guide - Setup, architecture, and customization
• Widget Usage Guide - Embedding examples and tool definitions

License

MIT