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.


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

{}
http

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.

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.


GET /api/v1/integration/widget/{widgetIntegrationId}/fetch
http

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 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.


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

{
  "name": "Updated Support Widget",
  "description": "Enhanced customer support chat interface",
  "botId": "bot_xyz789",
  "theme": "dark",
  "title": "How can we help you?",
  "intro": "Welcome! Ask us anything about our products and services.",
  "contactCollection": true,
  "voiceIn": true,
  "voiceOut": true,
  "attachments": true,
  "exportConversation": true
}
http

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.

Deleting Widget Integrations