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.

POST /api/v1/integration/widget/create
Content-Type: application/json

{
  "name": "Customer Support Widget",
  "description": "Interactive support chat for our main website",
  "botId": "bot_abc123",
  "theme": {
    "primaryColor": "#0066cc",
    "secondaryColor": "#f5f5f5",
    "fontFamily": "Inter, sans-serif"
  },
  "title": "How can we help you?",
  "placeholder": "Type your message here...",
  "contactCollection": true,
  "attachments": true,
  "voiceIn": true
}

http

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.

GET /api/v1/integration/widget/list

http

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.

GET /api/v1/integration/widget/list?take=10&cursor={nextCursor}

http

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.

POST /api/v1/integration/widget/{widgetIntegrationId}/session/create
Content-Type: application/json

{
  "contact": {
    "name": "John Smith",
    "email": "john@example.com"
  },
  "messages": [
    {
      "type": "user",
      "text": "Hello, I need help with my order"
    }
  ],
  "durationInSeconds": 3600
}

http

The response provides everything the widget needs to start interacting:

{
  "id": "widget_abc123",
  "conversationId": "conv_xyz789",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": 1735124400000,
  "messages": [
    {
      "type": "bot",
      "text": "Welcome! How can I help you today?"
    },
    {
      "type": "user",
      "text": "Hello, I need help with my order"
    }
  ]
}

json

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:

{
  "messages": [
    {
      "type": "user",
      "text": "I'm interested in pricing"
    }
  ]
}

json

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:

{
  "meta": {
    "source": "homepage",
    "campaign": "summer-2025",
    "utmSource": "google"
  }
}

json

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:

POST /api/v1/integration/widget/{widgetIntegrationId}/setup
Content-Type: application/json

{}

http

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:

{
  "id": "widget_abc123"
}

json

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
Go to cbk.ai