Widget Integration

The widget integration is one of the most popular ways to deploy conversational AI, allowing you to add intelligent chat capabilities to any website or web application with minimal technical implementation. Widget integrations provide a fully-featured chat interface that handles message exchange, file attachments, voice interactions, and rich content display, all while maintaining your brand identity through extensive customization options.

Widget integrations are designed to be embedded directly into web pages, appearing as a chat bubble or inline interface that users can interact with naturally. The widget handles all aspects of the conversation flow, including connection management, message streaming, error recovery, and responsive layout adjustments, providing a production-ready chat experience without requiring extensive frontend development.

Creating Widget Integrations

Creating a widget integration establishes a configured chat interface that can be embedded into your website. When you create a widget, you define its appearance, behavior, and capabilities through a comprehensive set of configuration options that control everything from visual theme to advanced features like voice input, file attachments, and contact collection.

The widget creation process begins by connecting the widget to a bot or blueprint that defines the conversational AI behavior. You then customize the widget's appearance and functionality to match your use case, brand guidelines, and user experience requirements. The system generates embed code that you can add to your website to activate the widget.

Configuration Options

Widget integrations support extensive configuration to tailor the chat experience to your specific needs:

Visual Customization:

• theme: Color scheme, fonts, and visual styling that match your brand identity. Supports custom CSS for advanced styling needs.
• layout: Widget layout mode (bubble, inline, fullscreen) that determines how the chat interface appears on your website.
• title: Welcome message or header text displayed at the top of the chat interface.
• intro: Introductory message shown when users first open the widget.

Interaction Settings:

• placeholder: Placeholder text shown in the message input field to guide users on what to type.
• initial: Initial message automatically sent when conversation starts, useful for greeting users or providing context.
• autoScroll: Automatically scroll to show the latest message as the conversation progresses.
• startFirst: Automatically send the initial message without requiring user action.

Advanced Features:

• attachments: Enable file upload capabilities, allowing users to share documents, images, and other files during conversations.
• voiceIn: Enable voice input, allowing users to speak their messages instead of typing.
• voiceOut: Enable voice output, allowing the bot to speak responses aloud using text-to-speech.
• contactCollection: Collect user contact information (name, email) before or during conversations for lead capture and support routing.
• tools: Enable function calling and tool use for advanced bot capabilities like API calls or data lookups.
• unfurl: Automatically preview links shared in conversations, displaying rich content previews.
• math: Enable mathematical expression rendering for technical support or educational use cases.
• carousel: Support carousel-style content display for product showcases or option selection.
• form: Enable structured form interactions within conversations.

Session and Privacy:

• sessionDuration: Maximum session duration in milliseconds (up to 1 hour). Controls how long conversation context is maintained.
• origin: Restrict widget usage to specific domains for security. Prevents unauthorized embedding.
• exportConversation: Allow users to export conversation transcripts for their records.
• restartConversation: Provide option to restart conversations, clearing history and starting fresh.

Technical Options:

• stream: Enable message streaming for real-time response delivery as the bot generates text.
• verbose: Include additional debugging information in widget console logs for troubleshooting.
• language: Set the default language for the widget interface and initial messages.
• plugins: Enable additional widget plugins for extended functionality.

Important Considerations:

• You must connect the widget to either a bot ID or blueprint ID to define the conversational behavior. Without this connection, the widget cannot process user messages.

• Theme customization should maintain sufficient contrast ratios for accessibility. Test your color scheme with accessibility tools before deploying to production.

• Enabling advanced features like voice input, file attachments, and contact collection may affect performance and require additional user permissions. Consider your target audience and use case when enabling these features.

• Session duration settings affect both user experience and resource consumption. Longer sessions maintain context better but consume more memory and may increase costs.

• The widget is responsive and mobile-optimized by default, automatically adapting its layout to different screen sizes and orientations.

Listing Widget Integrations

You can retrieve a list of all your widget integrations to manage deployed chat interfaces, review configuration settings, and monitor which widgets are active across your web properties. The list endpoint provides comprehensive information about each widget, including customization settings, feature flags, and resource associations.

This endpoint returns all widget integrations associated with your account, ordered by creation date with the most recent widgets appearing first. Each widget in the response includes its complete configuration, making it easy to audit settings or prepare for updates.

Pagination and Filtering

For accounts with many widget integrations, the API supports cursor-based pagination to efficiently retrieve large result sets. You can also filter widgets by metadata or blueprint association to find specific integrations quickly.

The take parameter controls how many widgets to retrieve in a single request, defaulting to a reasonable page size. The cursor parameter enables sequential navigation through your complete widget collection.

Response Structure

Each widget in the response includes comprehensive configuration details:

• Basic Information: Name, description, and identification
• Appearance: Theme, layout, title, intro message, and placeholder text
• Behavior: Session duration, language, streaming, and auto-scroll
• Features: Attachments, voice input/output, forms, math rendering
• Controls: Export, restart, maximize, and message peek options
• Branding: Powered-by display and origin restrictions
• Resources: Associated bot and blueprint references

Use the response data to build management interfaces, audit widget configurations, or synchronize settings across multiple widgets. The complete configuration data ensures you have full visibility into how each widget is configured and deployed.

Metadata Filtering: Include the meta query parameter to filter widgets by custom metadata key-value pairs. This is particularly useful when you've organized widgets using metadata tags for different clients, projects, or deployment environments.

Setting Up Widget Integrations

The setup operation prepares a widget integration for deployment by pre-generating and caching all required translation strings and configuration data. This setup process is essential for ensuring optimal widget performance, as it eliminates the need for real-time translation processing when users interact with the widget across different languages.

When you configure a widget with multiple languages, the system needs to translate all interface elements, placeholder text, button labels, and configuration messages into each specified language. Rather than performing these translations on-demand (which would introduce latency), the setup operation pre-generates a complete language map containing all translations, stores it in a cache, and associates it with the widget integration for instant retrieval.

To initialize the setup process for a widget integration, send a POST request to the setup endpoint:

The request body can be empty, as the setup operation uses the widget's existing configuration to determine what needs to be pre-generated. The system reads the language settings from the widget integration record and translates all relevant text elements including:

• Dialog confirmation messages (Yes/No buttons, restart prompts)
• Widget title bar text
• Control button labels (Language, Restart, Export, Maximize, Minimize)
• Input placeholder text
• Contact collection form labels (Name, Email fields)
• Introduction and initial message text

When to Run Setup

You should trigger the setup operation in these scenarios:

• After creating a new widget: Initial setup prepares the widget for first use
• After changing languages: When you modify the language configuration, setup regenerates translations
• After updating text content: Changes to title, placeholder, intro, or initial message require setup to update translations
• To force cache refresh: If translations seem stale or incorrect, setup clears and regenerates the language map

The setup operation forces cache invalidation by clearing any existing translations before generating new ones, ensuring that outdated translations don't persist after configuration changes.

Response Format

The API returns the widget integration ID upon successful setup:

Setup Performance

Translation generation is performed asynchronously to prevent request timeouts. The initial setup request returns immediately after queuing the translation work. Depending on the number of languages configured and the amount of text to translate, the full setup may take several seconds to complete. However, the widget will remain functional during this time using cached or default translations until the new translations are ready.

Important Notes:

• Setup must be performed by the widget integration owner
• Translation errors are captured but don't fail the setup operation; fallback text is used if translation fails
• The language map includes a default (untranslated) version that's always available
• Setup is idempotent - running it multiple times is safe and will simply regenerate translations
• Translations are cached with a unique key per widget integration to prevent conflicts