Agents Widget
API endpoints for Agents Widget
GET
/api/agents/{agent_id}/widget Get returns widget configuration for an agent.
Returns the widget configuration including theme, colors, messages, and allowed domains. Returns default config if none exists.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 404 | Resource not found |
Success
Response response.WidgetResponse
Widget
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique widget identifier |
| agent_id | integer (int64) | ID of agent this widget belongs to |
| display_name | string | null | Agent's display name in widget |
| initial_messages | object | Messages shown when chat starts |
| suggested_messages | object | Suggested quick-reply messages |
| placeholder_text | string | Placeholder text in message input |
| collect_feedback | boolean | Whether to enable feedback collection |
| allow_regenerate | boolean | Whether to allow response regeneration |
| notice_content | string | null | Notice banner content (HTML allowed) |
| footer_text | string | null | Footer text shown at bottom |
| popup_delay_seconds | integer (int32) | null | Delay in seconds before auto-showing popup |
| theme | string | Color theme: light, dark, or auto |
| profile_picture_url | string | null | URL to agent profile picture |
| chat_icon_url | string | null | URL to chat button icon |
| primary_color | string | Primary brand color (hex code) |
| use_primary_for_header | boolean | Use primary color for header background |
| bubble_color | string | null | Chat bubble background color (hex code) |
| button_position | string | Chat button position: left or right |
| allowed_domains | object | Domains allowed to embed the widget |
| is_enabled | boolean | Whether the widget is enabled |
| token | string | Embed token for public widget access |
| created_at | string (date-time) | Timestamp when widget was created |
| updated_at | string (date-time) | Timestamp when widget was last updated |
POST
/api/agents/{agent_id}/widget Store saves widget configuration.
Updates the widget's theme, colors, messages, and other settings. Creates a new widget config if none exists.
Request Body request.Widget
Widget
| Property | Type | Description |
|---|---|---|
| display_name | string | null | Agent's display name shown in widget |
| initial_messages | string | Messages shown when chat starts |
| suggested_messages | string | Suggested quick-reply messages |
| placeholder_text | string | null | Placeholder text in message input |
| collect_feedback | boolean | null | Enable feedback collection (thumbs up/down) |
| allow_regenerate | boolean | null | Allow users to regenerate responses |
| notice_content | string | null | Notice banner content (HTML allowed) |
| footer_text | string | null | Footer text shown at bottom of widget |
| popup_delay_seconds | integer (int32) | null | Delay in seconds before auto-showing popup (0-300) |
| theme | "light" | "dark" | "auto" | Color theme: light, dark, or auto |
| profile_picture_url | string | null | URL to agent profile picture |
| chat_icon_url | string | null | URL to chat button icon |
| primary_color | string | null | Primary brand color (hex code) |
| use_primary_for_header | boolean | null | Use primary color for header background |
| bubble_color | string | null | Chat bubble background color (hex code) |
| button_position | "left" | "right" | Chat button position: left or right |
| allowed_domains | string | Domains allowed to embed the widget |
| is_enabled | boolean | null | Whether the widget is enabled |
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 404 | Resource not found |
| 422 | Validation failed |
| 500 | Internal server error |
Success
Response response.WidgetResponse
Widget
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique widget identifier |
| agent_id | integer (int64) | ID of agent this widget belongs to |
| display_name | string | null | Agent's display name in widget |
| initial_messages | object | Messages shown when chat starts |
| suggested_messages | object | Suggested quick-reply messages |
| placeholder_text | string | Placeholder text in message input |
| collect_feedback | boolean | Whether to enable feedback collection |
| allow_regenerate | boolean | Whether to allow response regeneration |
| notice_content | string | null | Notice banner content (HTML allowed) |
| footer_text | string | null | Footer text shown at bottom |
| popup_delay_seconds | integer (int32) | null | Delay in seconds before auto-showing popup |
| theme | string | Color theme: light, dark, or auto |
| profile_picture_url | string | null | URL to agent profile picture |
| chat_icon_url | string | null | URL to chat button icon |
| primary_color | string | Primary brand color (hex code) |
| use_primary_for_header | boolean | Use primary color for header background |
| bubble_color | string | null | Chat bubble background color (hex code) |
| button_position | string | Chat button position: left or right |
| allowed_domains | object | Domains allowed to embed the widget |
| is_enabled | boolean | Whether the widget is enabled |
| token | string | Embed token for public widget access |
| created_at | string (date-time) | Timestamp when widget was created |
| updated_at | string (date-time) | Timestamp when widget was last updated |
POST
/api/agents/{agent_id}/widget/regenerate-token RegenerateToken
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
POST
/api/agents/{agent_id}/widget/upload Asset handles widget asset uploads (profile picture, chat icon).
Accepts a base64-encoded image file (png, jpg, gif, webp) up to 1MB. The type field specifies whether this is a profile_picture or chat_icon.
Request Body request.WidgetAsset
Widget Asset
| Property | Type | Description |
|---|---|---|
| type* | "profile_picture" | "chat_icon" | Asset type: profile_picture or chat_icon |
| file_base64* | string | Base64-encoded image file |
| file_filename* | string | Original filename with extension |
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 404 | Resource not found |
| 422 | Validation failed |
| 500 | Internal server error |
Success
Response response.WidgetResponse
Widget
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique widget identifier |
| agent_id | integer (int64) | ID of agent this widget belongs to |
| display_name | string | null | Agent's display name in widget |
| initial_messages | object | Messages shown when chat starts |
| suggested_messages | object | Suggested quick-reply messages |
| placeholder_text | string | Placeholder text in message input |
| collect_feedback | boolean | Whether to enable feedback collection |
| allow_regenerate | boolean | Whether to allow response regeneration |
| notice_content | string | null | Notice banner content (HTML allowed) |
| footer_text | string | null | Footer text shown at bottom |
| popup_delay_seconds | integer (int32) | null | Delay in seconds before auto-showing popup |
| theme | string | Color theme: light, dark, or auto |
| profile_picture_url | string | null | URL to agent profile picture |
| chat_icon_url | string | null | URL to chat button icon |
| primary_color | string | Primary brand color (hex code) |
| use_primary_for_header | boolean | Use primary color for header background |
| bubble_color | string | null | Chat bubble background color (hex code) |
| button_position | string | Chat button position: left or right |
| allowed_domains | object | Domains allowed to embed the widget |
| is_enabled | boolean | Whether the widget is enabled |
| token | string | Embed token for public widget access |
| created_at | string (date-time) | Timestamp when widget was created |
| updated_at | string (date-time) | Timestamp when widget was last updated |