Widget Configuration¶

Overview¶

Your Rose account manager configures the widget behavior through our configuration system. This page documents all available settings and their effects.

Basic Settings¶

Setting	Description	Default
`color`	Primary brand color (hex code)	`#0A42C3`
`default_language`	Default language for the widget	`en`
`session_utm_name`	UTM parameter name for session tracking	None

Display Settings¶

For a complete flowchart of how these settings interact to determine widget visibility, see Widget Display Logic.

Traffic Control¶

Controls what percentage of visitors see the widget. See Traffic Control for details.

URL Restrictions¶

Include Only Specific URLs (`display_only_on_urls`)¶

If set, the widget only appears on URLs matching these patterns. Supports wildcards.

Example:

["https://www.example.com/pricing*", "https://www.example.com/demo*"]

The widget will only display on pricing and demo pages.

Exclude URLs (`exclude_url_patterns`)¶

URLs matching these patterns will never show the widget. Useful for excluding blog, admin, or login pages.

Example:

["www.example.com/blog*", "www.example.com/admin*", "www.example.com/login"]

Mobile Support (`enable_mobile`)¶

By default, the widget is hidden on mobile devices. Set to true to enable mobile display.

Value	Behavior
`false` (default)	Widget hidden on mobile
`true`	Widget visible on mobile

Z-Index (`z_index`)¶

Controls the stacking order of the widget relative to other elements on your page.

Value	Description
`9999` (default)	Widget appears above most elements
Higher values	Widget appears above elements with lower z-index

If your site has modals, sticky headers, or other high z-index elements that overlap the widget, your account manager can adjust this value.

Call-to-Action (CTA) Buttons¶

CTAs are the action buttons displayed in the chat (e.g., "Book a Demo", "Start Free Trial").

CTA Structure¶

Each CTA has:

Field	Description
`placeholder`	Internal identifier used by the AI to reference this CTA
`cta_id`	Semantic identifier for analytics (e.g., "demo-cta", "free-trial")
`langs`	Language-specific URL and button text

Example:

{
  "placeholder": "{{DEMO_CTA}}",
  "cta_id": "demo-cta",
  "langs": {
    "en": { "url": "/book-demo", "text": "Book a Demo" },
    "fr": { "url": "/fr/reserver-demo", "text": "Réserver une démo" }
  }
}

CTA Destination Tracking¶

Rose automatically tracks when users land on CTA destination pages. Additional tracking pages can be configured:

Setting	Description
`additional_cta_destinations`	URLs to track as CTA destinations (without showing buttons)
`additional_form_tracking_pages`	Pages where form submission tracking is enabled
`thank_you_pages`	Thank-you/confirmation page patterns for form submission detection

Dynamic Questions¶

Dynamic questions are the suggested questions displayed in the collapsed widget state.

Simple Format¶

A list of questions per language:

{
  "en": ["What does Rose do?", "How does pricing work?", "Can I see a demo?"],
  "fr": ["Que fait Rose ?", "Comment fonctionne la tarification ?"]
}

Advanced Format (Per-Page Questions)¶

Different questions for different pages:

{
  "en": {
    "default": ["What does Rose do?", "How does pricing work?"],
    "pages": [
      {
        "patterns": ["*/pricing*"],
        "questions": ["What's included in each plan?", "Do you offer annual discounts?"]
      },
      {
        "patterns": ["*/blog*"],
        "questions": []
      }
    ]
  }
}

default: Questions shown when no pattern matches
pages: Array of page-specific rules
patterns: URL patterns (supports wildcards)
questions: Questions for matching pages (empty array hides questions)

Conversation Display¶

Follow-up Suggestions (`disable_followup_suggestions`)¶

Controls whether AI-generated follow-up questions appear after responses:

Value	Behavior
`false` (default)	Follow-up suggestions shown
`true`	Follow-up suggestions hidden

Booking Flow¶

In-Chat Email Collection (`booking_workflow`)¶

When a visitor clicks a booking CTA (e.g., "Book a Demo"), Rose can collect their email address through the conversation before redirecting them to the booking page. This allows the booking page to be pre-filled with the visitor's email, reducing friction and improving conversion rates.

Why collect email in the chat?

Better lead capture: Even if the visitor doesn't complete the booking, you've captured their email
Personalized experience: The conversation feels more natural than a cold form

How it works:

Visitor clicks a booking CTA
If their email is unknown, Rose asks for it in the chat
Once provided, the visitor is redirected with ?email=xxx appended to the URL
If the email is already known (from a previous session), the redirect happens immediately

Configuration:

Value	Behavior
`false` (default)	Visitors are immediately redirected, no email collection
`true`	Rose collects email in chat before redirecting

This feature is disabled by default. To enable it for a specific site, set booking_workflow: true in the site's custom_config. The global default can also be changed via global_client_config.features.booking_workflow.

Priority logic:

Site-specific setting in custom_config.booking_workflow (if set)
Global setting in global_client_config.features.booking_workflow
Default: false (disabled)

CTA Page Behavior¶

Hide Widget on CTA Pages (`hide_search_bar_on_cta_pages`)¶

When enabled, the widget is completely hidden on CTA destination pages (e.g., demo booking pages) to avoid distracting users during conversion.

Value	Behavior
`false` (default)	Widget visible on CTA pages
`true`	Widget hidden on CTA pages

Always Show Disclaimer (`always_show_disclaimer`)¶

Controls when the AI disclaimer is displayed:

Value	Behavior
`false` (default)	Disclaimer shown only on first interaction
`true`	Disclaimer always visible

Custom Disclaimers¶

Override the default AI disclaimer text per language:

{
  "en": {
    "ai": "Responses are AI-generated and may not be accurate.",
    "poweredBy": "Powered by Rose AI"
  },
  "fr": {
    "ai": "Les réponses sont générées par IA et peuvent être inexactes.",
    "poweredBy": "Propulsé par Rose AI"
  }
}

Analytics Configuration¶

URLs that indicate a logged-in user session to exclude those people from analytics (they are clients):

{
  "login_urls": ["/dashboard", "/app", "/account"]
}

Event Forwarding¶

Control how analytics events are forwarded to your page. See Event Forwarding for details.

{
  "analytics_providers": {
    "parent_window_events": {
      "enabled": true,
      "target_origin": "*",
      "event_categories": ["user_action", "conversion", "system"]
    }
  }
}

Need Changes?¶

Contact your Rose account manager to adjust any of these settings for your site or if you think you need new parameters.

Widget Configuration¶

Overview¶

Basic Settings¶

Display Settings¶

Traffic Control¶

URL Restrictions¶

Include Only Specific URLs (display_only_on_urls)¶

Exclude URLs (exclude_url_patterns)¶

Mobile Support (enable_mobile)¶

Z-Index (z_index)¶

Call-to-Action (CTA) Buttons¶

CTA Structure¶

CTA Destination Tracking¶

Dynamic Questions¶

Simple Format¶

Advanced Format (Per-Page Questions)¶

Conversation Display¶

Follow-up Suggestions (disable_followup_suggestions)¶

Booking Flow¶

In-Chat Email Collection (booking_workflow)¶

CTA Page Behavior¶

Hide Widget on CTA Pages (hide_search_bar_on_cta_pages)¶

Always Show Disclaimer (always_show_disclaimer)¶

Custom Disclaimers¶

Analytics Configuration¶

Login URLs¶

Event Forwarding¶

Need Changes?¶

Include Only Specific URLs (`display_only_on_urls`)¶

Exclude URLs (`exclude_url_patterns`)¶

Mobile Support (`enable_mobile`)¶

Z-Index (`z_index`)¶

Follow-up Suggestions (`disable_followup_suggestions`)¶

In-Chat Email Collection (`booking_workflow`)¶

Hide Widget on CTA Pages (`hide_search_bar_on_cta_pages`)¶

Always Show Disclaimer (`always_show_disclaimer`)¶