Developer Guide
Technical integration reference
This guide covers the technical details of the Ultimo Bots widget, including how it loads, how it is styled, how sessions work, and the key API endpoints for advanced integrations.
Widget fundamentals
Script tag embedding
Add the Ultimo widget to any page by pasting the script tag before the closing body tag. The script takes a data-user-id attribute that identifies your bot.
Shadow DOM isolation
The widget renders inside a Shadow DOM, ensuring your site styles do not interfere with the chat interface and vice versa.
Deferred loading
The widget bundle is loaded with defer so it does not block your page rendering. The chat interface appears after the page finishes loading.
Mobile full-screen
On mobile devices, the widget automatically switches to full-screen mode for a better chat experience.
Customization and theming
CSS variables
The widget supports CSS custom properties for theming. Colors set in the Design tab are applied via CSS variables inside the Shadow DOM.
Font loading
The widget uses Web Font Loader to load 20+ Google Fonts. The font selected in Design settings is loaded dynamically when the widget initializes.
Custom images
Widget icon, header logo, and bot avatar are loaded from Azure Blob Storage URLs configured in Design settings.
Configurable dimensions
Widget size, border radius, and vertical position are all configurable from the portal and applied via inline styles.
Sessions and data handling
Session tracking
The widget stores a session ID in sessionStorage, maintaining conversation continuity as visitors navigate between pages on your site.
Pre-chat form
When Enforce Contact Details is enabled, the widget displays a form overlay before the chat begins. Visitors must fill in required fields to start chatting.
Markdown rendering
Bot responses support markdown formatting via marked.js, including bold, italic, links, lists, and inline code.
Widget vs. Iframe mode
The embed snippet supports two modes: widget (floating chat bubble) and iframe (full-page chat). Toggle between them on the Integration page.
Key API endpoints
Chat API
GET /api/chatbot_response -- SSE streaming endpoint that returns bot responses token by token. Accepts bot_id, prompt, session_id, voice_enabled, and language as query parameters.
Voice API
POST /api/voice_message -- Accepts audio files (multipart) and returns transcribed text plus bot response via SSE. Uses OpenAI Whisper for transcription and Google Cloud TTS for audio responses.
Widget Configuration
GET /api/widget_configuration/{bot_id} -- Public endpoint that returns all visual and behavioral settings for the widget. No authentication required.
WebSocket notifications
Connect to /ws with a user_id query parameter to receive real-time updates about bot creation progress, behavior training status, and other events.
Developer tips
- Always test the widget in an incognito window to catch caching issues after making changes.
- The Shadow DOM prevents style leaks, but ensure your Content Security Policy allows the widget script domain.
- Use the Share Link integration to test the widget in isolation before embedding on your live site.
- Session tracking relies on sessionStorage, so each browser tab maintains its own conversation state.
- For advanced customization beyond what the portal offers, contact support for CSS override guidance.