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.

Creating Widget Sessions

Creating a widget session establishes an authenticated connection between your widget integration and a conversation, enabling real-time chat interactions with your bot. This endpoint is the foundation of widget communication, generating secure session tokens and initializing conversations with optional contact information and message history.

Widget sessions are temporary authenticated connections that allow the widget client to interact with the ChatBotKit API on behalf of a user. Each session is scoped to a single conversation and includes security tokens, conversation identifiers, and configuration that determines how the widget behaves during the interaction.

When you create a widget session, the platform automatically creates a new conversation (or can attach to an existing one), processes any initial messages, collects contact information if provided, and returns everything needed for the widget to begin interactive chat.

The response provides everything the widget needs to start interacting:

Session Configuration

Duration Management:

The durationInSeconds parameter controls how long the session remains valid:

• Minimum: 1,800 seconds (30 minutes)
• Maximum: 86,400 seconds (24 hours)
• Default: Uses the widget's configured sessionDuration setting

Sessions automatically expire after the specified duration, requiring users to create new sessions for continued interaction. Choose durations based on your use case - shorter durations improve security, while longer durations provide better user experience for extended interactions.

Contact Collection:

The optional contact object enables lead capture and user identification:

• name: User's full name (optional)
• email: Valid email address (optional, validated)
• phone: Phone number in international format (optional, validated)

When contact information is provided, the platform automatically creates or updates contact records, enabling you to track users across conversations and maintain persistent user profiles. Contact information is only collected if the widget's contactCollection setting is enabled.

Initial Messages:

The messages array allows you to seed the conversation with context or user input collected before session creation:

Initial messages appear in the conversation history immediately, and the bot processes them before returning, so responses are included in the session creation response. This enables pre-seeding conversations with context or handling form submissions that trigger chat interactions.

Important Notes:

• Only user type messages are allowed in the messages array to prevent potential prompt injection or bot behavior manipulation

• If the widget has an initial message configured, it's automatically prepended as a bot message before any user messages

• The widget integration must have a bot configured (botId) to process messages; sessions without bot configuration will fail

Session Security:

The returned token is a JWT that grants limited access to the conversation API on behalf of the widget owner. This token:

• Grants read/write access only to the specific conversation
• Expires automatically after the session duration
• Cannot be refreshed - new sessions must be created after expiration
• Should be treated as sensitive and not logged or exposed publicly

Metadata and Tracking

Use the optional meta parameter to attach custom metadata to the conversation:

Metadata is preserved throughout the conversation lifecycle and can be used for analytics, routing, and reporting purposes. The platform automatically adds app: "widget" and widgetIntegrationId to track widget-initiated conversations.

Advanced Features

Widget sessions automatically respect the widget's configuration:

• Attachments: If enabled, users can upload files during conversations
• Math Rendering: Mathematical expressions are formatted if enabled
• Carousels: Carousel UI elements are supported if configured
• Forms: Structured form interactions are available if enabled

These features are controlled by the widget integration settings and cannot be overridden during session creation, ensuring consistent behavior across all widget instances.

Performance Optimizations:

The session creation endpoint includes several optimizations for widget deployments:

• Widget configuration is cached with SWR strategy for low-latency responses
• Inline dataset and skillset features are disabled to improve response times
• Rate limiting is applied per-session to prevent abuse
• Message processing happens synchronously so initial responses are immediate

These optimizations ensure fast widget loading and responsive interactions, critical for maintaining good user experience in chat interfaces.

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

Cloning Widget Integrations

The widget cloning functionality enables you to duplicate existing widget integrations with all their configurations, creating new instances that inherit the complete setup of the original widget. This is particularly useful when you need to deploy similar chat widgets across multiple websites, create variations for A/B testing, or establish development and production versions of the same widget with minimal manual configuration.

When you clone a widget integration, the system creates a complete copy that includes all visual customization settings (theme, layout, title, intro, placeholder text), interaction configurations (session duration, language, streaming behavior, plugins), feature enablements (attachments, voice, tools, forms, contact collection), blueprint association, and associated file attachments. The cloned widget receives a new unique identifier but maintains all the functional characteristics of the source widget, allowing you to deploy it independently while preserving tested configurations.

The cloning operation is particularly valuable in several scenarios. When managing multiple websites or applications that require similar chat experiences, you can establish a well-configured template widget and clone it for each deployment, ensuring consistency while allowing for minor per-instance customizations after cloning. For testing and development workflows, you can clone production widgets to create safe testing environments where changes can be validated before affecting live systems.

The cloned widget maintains references to the same bot, datasets, and skillsets as the original, but operates as an independent integration with its own usage tracking, session management, and configuration lifecycle. This means you can modify the clone's settings, embed code, or associated resources without affecting the source widget, providing flexibility for experimentation and specialized deployments.

After cloning, you'll receive the new widget's unique identifier, which you can use to retrieve embed code, update configurations, or manage the cloned instance through the standard widget integration endpoints. The cloned widget is immediately ready for deployment and will function identically to the source widget until you make configuration changes.

Important Considerations:

• File attachments associated with the original widget are referenced in the clone, not duplicated, so modifications to shared files affect both widgets
• The clone inherits the original's bot association, so both widgets will use the same AI model and training unless you update the clone's bot reference
• If the source widget is linked to a blueprint, the clone inherits the same blueprintId reference and will receive configuration updates pushed from that blueprint unless you detach it after cloning
• Plugin configurations (plugins) are copied from the source widget, enabling the same custom integrations and extensions in the cloned widget
• Usage metrics, conversation history, and analytics for the cloned widget are tracked separately from the original
• Theme customizations and visual settings are copied but can be modified independently after cloning
• The cloned widget requires separate embed code generated specifically for its unique identifier

Deleting Widget Integrations

Deleting a widget integration permanently removes the widget configuration and all associated settings from your account. This operation is irreversible and should be used carefully, particularly for widgets that are actively embedded on websites or applications.

When you delete a widget integration, the widget will immediately stop functioning on any websites where it's embedded. Users attempting to interact with the widget will no longer be able to start conversations or receive responses. This makes deletion particularly important to handle carefully for production deployments.

Before Deleting

Before deleting a widget integration, consider these important factors to avoid service disruption and data loss:

Check Active Usage: Verify whether the widget is currently embedded on any websites or applications. Removing an actively-used widget will immediately break functionality for end users visiting those pages.

Review Conversation History: Ensure you've exported any important conversation data or analytics from the widget's usage history. Once deleted, the widget configuration is removed, though associated conversation data may be preserved separately depending on your settings.

Consider Disabling First: For widgets in active use, consider updating the widget configuration to disable it or modify its behavior rather than immediately deleting it. This provides a safer rollback path if needed.

Update Embeddings: Remove the widget embed code from all websites and applications before deletion, or ensure you have a replacement widget ready to deploy to avoid service interruption.

What Gets Deleted

The deletion operation removes the widget integration entity and all its configuration settings including appearance customization, feature flags, behavioral settings, and security configurations.

The connected bot, datasets, and other resources are NOT deleted - only the widget integration itself is removed. This means you can create a new widget integration using the same bot and resources if needed.

After Deletion

After deleting a widget integration:

Embedded Widgets Stop Working: Any embedded instances of the widget will no longer function and may display errors or simply fail to load.

ID Becomes Invalid: The widget integration ID can no longer be used for API operations and will return "not found" errors if referenced.

Configuration Is Lost: All widget settings and customizations are permanently removed and cannot be recovered. You'll need to reconfigure from scratch if creating a replacement widget.

Warning: This operation is permanent and cannot be undone. Ensure you have backups of any important configuration or that you're prepared to reconfigure the widget if needed later.

Fetching Widget Integration Details

Retrieving widget integration details provides comprehensive information about a specific widget's configuration, settings, and current state. This is essential for displaying widget settings in your application, debugging configuration issues, or programmatically managing widget properties based on their current values.

The fetch operation returns the complete widget configuration including all appearance settings, feature flags, behavioral controls, and metadata. This allows you to inspect the widget's current state before making updates or to display configuration information to users managing the widget.

Response Structure

The response includes comprehensive widget information organized into several categories:

Identification: The widget's unique ID, name, and description that identify and describe the widget instance.

Resource Linking: References to connected resources including the botId (associated conversational bot) and blueprintId (configuration template if using blueprints for centralized management).

Appearance Configuration: Visual and interface settings including theme (color scheme), layout (interface structure), title (header text), intro (welcome message), initial (first automated message), placeholder (input hint text), and language (interface language).

Feature Flags: Boolean settings that enable or disable specific capabilities such as attachments, voiceIn, voiceOut, form, carousel, math, unfurl, contactCollection, exportConversation, restartConversation, maximize, messagePeek, and poweredBy branding.

Behavioral Settings: Configuration that controls widget behavior including sessionDuration (conversation persistence time), stream (real-time response streaming), verbose (detailed logging), tools (enable tool usage), autoScroll (automatic scrolling), and startFirst (auto-initiate conversations).

Security Settings: The origin parameter that restricts which domains can embed and use the widget, providing security through domain whitelisting.

Use Cases

Fetching widget details is valuable for several scenarios:

Configuration Management: Retrieve current settings before making updates to ensure you only change specific parameters while preserving others.

Dashboard Display: Show widget configuration in management interfaces so users can review and understand their widget settings.

Conditional Updates: Check current feature flags or settings before applying conditional logic or updates based on the widget's state.

Troubleshooting: Inspect widget configuration when debugging issues with appearance, behavior, or feature availability to identify misconfigurations.

Audit and Compliance: Review widget settings for security compliance, ensuring appropriate features are enabled or disabled based on requirements.

Updating Widget Integrations

Updating a widget integration allows you to modify its configuration, appearance, behavior, and feature settings without recreating the widget. This is essential for iterating on your chat widget design, adjusting user experience settings, and enabling or disabling features based on your evolving requirements.

Widget integrations support extensive customization options including visual themes, conversational behavior, feature toggles, and user interaction controls. You can update the connected bot, modify the interface text and styling, configure session settings, and control which features are available to your users.

Configuration Options

The widget update endpoint supports numerous configuration parameters that control every aspect of the widget's appearance and functionality:

Appearance Settings: Control the visual presentation with theme (color scheme), layout (interface arrangement), title (header text), intro (welcome message), and placeholder (input field hint text).

Behavioral Settings: Configure session behavior with sessionDuration to control how long conversations persist, startFirst to automatically initiate conversations, and autoScroll to manage message scrolling behavior.

Feature Toggles: Enable or disable specific capabilities including attachments (file uploads), voiceIn (speech input), voiceOut (audio responses), form (form rendering), carousel (carousel messages), math (mathematical expressions), and unfurl (link previews).

User Controls: Manage user-facing controls such as contactCollection (collect user contact information), exportConversation (allow conversation downloads), restartConversation (enable conversation reset), maximize (fullscreen mode), and messagePeek (preview initial messages).

Technical Settings: Configure technical aspects like stream (enable streaming responses), verbose (detailed logging), tools (enable tool usage), language (interface language), and origin (allowed domains for security).

Important Considerations

Domain Security: The origin parameter controls which domains can embed and use your widget. Configure this carefully to prevent unauthorized use and ensure your widget only appears on approved websites.

Session Duration: The sessionDuration parameter has a maximum limit of one hour. Longer sessions may impact performance and resource usage, while shorter sessions ensure fresher conversation contexts.

Blueprint Inheritance: If you update the blueprintId, the widget will inherit configuration from the new blueprint. This allows you to manage multiple widgets with shared settings through blueprint updates.

Feature Dependencies: Some features have dependencies on others. For example, voice features require browser support, and forms require specific bot configurations. Test thoroughly when enabling new features.