A React-based embeddable chat widget that connects to a Soliplex/PydanticAI backend using the AG-UI protocol. Supports OIDC authentication via popup flow.
# Install dependencies
npm install
# Start development server
npm run dev
# Run the tests
npm test
# Build embeddable widget
npm run build:widgetAdd 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:
- If no
baseUrlis configured, show a server URL prompt - Check if authentication is required (fetches
/api/login) - If auth is configured, show a login screen with available providers
- After authentication (or if no auth required), fetch available rooms from
/api/v1/rooms - Display a room selector if multiple rooms exist, or auto-select if only one
The widget takes options for room selection (roomId, roomIds,
fallbackRoomIds), appearance (title, bubbleColor, theme, position),
persistence, and client-side tools. See
Configuration Options in the usage
guide for the full reference.
The widget supports OIDC authentication through the Soliplex backend. When auth systems are configured on the backend:
- The widget fetches available auth providers from
/api/login - User clicks a provider button to start OAuth flow
- A popup window opens for authentication (no page redirect)
- On success, tokens are passed back to the widget via
postMessage - All subsequent API calls include the Bearer token
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.
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-----The widget needs a running Soliplex backend. The quickest way to get one is
the soliplex-template Docker
Compose stack: follow its "Try it" section, and see its
documentation for ports,
authentication, and configuring rooms. The stack serves the API through nginx
at http://localhost:9000, which is the backend the demo page uses.
Then build the widget and serve the demo page:
npm run build:widget:watch
# In another terminal
cd public
python -m http.server 8080
# Open http://localhost:8080/- Development Guide - Setup, architecture, and customization
- Widget Usage Guide - Embedding examples and tool definitions
MIT