Actions Configuration

Action buttons are interactive elements that can be attached to assistant messages, enabling users to perform actions like triggering handovers, opening URLs, sending custom events, or submitting queries. Actions provide a powerful way to create guided conversation flows and interactive experiences.

Overview

Actions can be provided to the widget in two ways:

Query Response - The Nexus backend can include actions in the query response that get automatically attached to assistant messages
Message Interceptor - Your custom messageInterceptor function can return actions in the InterceptorAssistantMessage.actions field

Both methods use the same ActionsConfig interface to configure action buttons, their behavior, and styling.

Action Types

Four action types are supported:

trigger_handover - Triggers a handover to a live agent with optional reason, priority, and metadata
open_url - Opens a URL in a specified target (_blank, _self, etc.)
send_event - Sends a custom event that can be captured via the widget’s event system
send_query - Submits a query to the backend (with optional display text)

Quick Example

// In messageInterceptor or query response:
{
text: "How would you like to proceed?",
role: "assistant",
actions: {
  alignment: "center",
  spacing: "12px",
  actions: [
    {
      id: "contact-sales",
      label: "Contact Sales",
      icon: { type: "emoji", content: "📞" },
      action: {
        type: "trigger_handover",
        payload: {
          reason: "customer_inquiry",
          priority: "high"
        }
      },
      style: {
        backgroundColor: "#10b981",
        textColor: "#ffffff"
      }
    },
    {
      id: "learn-more",
      label: "Learn More",
      action: {
        type: "open_url",
        url: "https://example.com/pricing",
        target: "_blank"
      }
    }
  ]
}
}

Complete Reference

Complete reference for ActionBehavior and PostClickBehavior configuration options.

ActionBehavior

The ActionBehavior interface controls action button lifecycle, state, and post-click behavior. All properties are optional.

Properties

oneTimeUse

Type: boolean Default: false

Disables the action button after the first click. Useful for actions that should only be triggered once, such as “Request Callback” or “Download Report”.

Behavior:

When clicked, the button is marked as “used” and disabled
The button receives disabledReason: "used"
Does not apply to send_query action types (which have their own handling)

Example:

{
  id: "request-callback",
  label: "Request Callback",
  action: { type: "send_event", eventName: "callback_requested" },
  behavior: {
    oneTimeUse: true  // Disable after first click
  }
}

disableAllOnClick

Type: boolean Default: false

When combined with oneTimeUse: true, clicking this button disables ALL buttons in the action group. Perfect for mutually exclusive choices like plan selection or confirm/cancel scenarios.

Requirements:

MUST be used with oneTimeUse: true
Both properties must be set for this to work

Behavior:

When clicked, ALL actions in the message are immediately disabled
All buttons receive disabledReason: "used"
Useful for preventing multiple selections in choice scenarios

Example:

{
  actions: [
    {
      id: "select-basic",
      label: "Basic Plan",
      action: { type: "send_event", eventName: "plan_selected" },
      behavior: {
        oneTimeUse: true,
        disableAllOnClick: true, // Disable all when clicked
      },
    },
    {
      id: "select-pro",
      label: "Pro Plan",
      action: { type: "send_event", eventName: "plan_selected" },
      behavior: {
        oneTimeUse: true,
        disableAllOnClick: true, // Disable all when clicked
      },
    },
  ];
}

expiresAfterTurns

Type: number Default: undefined (no expiration)

Auto-disables the action after N conversation turns. A “turn” consists of a user message followed by an assistant response. Useful for time-sensitive offers or context-dependent actions.

Behavior:

Counts conversation turns from when the action was added
When the turn limit is reached, button is disabled with disabledReason: "expired"
If not set, actions from previous turns auto-disable with disabledReason: "outdated"

Example:

{
  id: "special-offer",
  label: "View Limited Offer",
  action: { type: "open_url", url: "https://example.com/offer" },
  behavior: {
    expiresAfterTurns: 1  // Expires after next turn
  }
}

Note: Setting expiresAfterTurns allows fine-grained control over action availability, overriding the default behavior of disabling previous-turn actions.

disabled

Type: boolean Default: false

Manually disables the button at configuration time. The button will be rendered in a disabled state and will not respond to clicks.

Behavior:

Sets initial disabled state when action is created
Runtime state changes (from oneTimeUse, expiresAfterTurns, etc.) take precedence
Button is visually grayed out and not clickable

Use Cases:

Conditional feature availability based on user permissions
Form validation scenarios (enable after requirements met)
Progressive disclosure (enable after previous steps complete)

Example:

{
  id: "premium-feature",
  label: "Access Premium Feature",
  action: { type: "open_url", url: "https://example.com/premium" },
  behavior: {
    disabled: true,  // Initially disabled
    disabledReason: "Upgrade to premium to access this feature"
  }
}

disabledReason

Type: string Default: undefined

Custom tooltip text displayed when the button is disabled. Helps users understand why an action is unavailable.

Behavior:

Displayed as the button’s title attribute (browser tooltip)
Custom reason is only shown if no runtime reason exists
Runtime reasons ("used", "expired", "outdated") take precedence

Priority Order:

Runtime reasons (highest priority)
Custom disabledReason from config
No tooltip if neither is set

Example:

{
  id: "checkout",
  label: "Proceed to Checkout",
  action: { type: "open_url", url: "https://example.com/checkout" },
  behavior: {
    disabled: true,
    disabledReason: "Add items to cart before checkout"  // Shows in tooltip
  }
}

postClickBehavior

Type: PostClickBehavior Default: undefined

Defines confirmation feedback displayed after the action button is clicked. See PostClickBehavior section below for complete documentation.

Example:

{
  id: "subscribe",
  label: "Subscribe",
  action: { type: "send_event", eventName: "newsletter_subscribe" },
  behavior: {
    oneTimeUse: true,
    postClickBehavior: {
      confirmationMessage: "Successfully subscribed to our newsletter!",
      confirmationIcon: { type: "emoji", content: "✅" }
    }
  }
}

Property Interactions

oneTimeUse + disableAllOnClick

Both must be true for disableAllOnClick to function:

If only disableAllOnClick: true, no effect
If only oneTimeUse: true, only the clicked button disables
If both true, ALL buttons disable on any click

oneTimeUse with send_query actions

send_query actions automatically trigger “disable all” behavior regardless of disableAllOnClick value, preventing multiple simultaneous queries.

expiresAfterTurns with auto-outdating

If expiresAfterTurns is set: Expires at exact turn count with disabledReason: "expired"
If not set: Previous turn actions auto-disable with disabledReason: "outdated"
Allows fine-grained control over action availability

Runtime disabledReason vs. config disabledReason

Runtime reasons ("used", "expired", "outdated") always take precedence
Custom disabledReason only used when no runtime reason exists
Runtime reasons auto-translate to user-friendly tooltip messages

Complete Example

{
  id: "confirm-appointment",
  label: "Confirm Appointment",
  icon: { type: "emoji", content: "📅" },
  action: {
    type: "send_event",
    eventName: "appointment_confirmed",
    eventData: { appointmentId: "12345" }
  },
  style: {
    backgroundColor: "#10b981",
    textColor: "#ffffff"
  },
  behavior: {
    oneTimeUse: true,
    disableAllOnClick: true,
    expiresAfterTurns: 2,
    postClickBehavior: {
      confirmationMessage: "✅ Appointment confirmed! You'll receive a confirmation email shortly.",
      confirmationMessageFormat: "text",
      confirmationMessageAlignment: "center",
      confirmationMessageColor: "#10b981",
      removeOnClick: true
    }
  }
}

PostClickBehavior

The PostClickBehavior interface defines confirmation feedback displayed after an action button is clicked. All properties are optional.

Properties

removeOnClick

Type: boolean Default: false

Removes all action buttons from the message after the button is clicked. Useful for one-time choices or when actions are no longer relevant after user interaction.

Behavior:

Sets message.metadata.actions = undefined
Sets message.metadata.actionStates = undefined
Removes entire action button group from the message

Example:

{
  behavior: {
    postClickBehavior: {
      removeOnClick: true,  // Remove all buttons after click
      confirmationMessage: "Thank you for your selection!"
    }
  }
}

confirmationMessage

Type: string Default: undefined (no confirmation)

Message to display after the button is clicked. Supports markdown, HTML, or plain text formatting based on confirmationMessageFormat.

Behavior:

Triggers entire confirmation UI rendering pipeline
Rendered using ContentRenderer component
Supports rich formatting with markdown/HTML

Example:

{
  behavior: {
    postClickBehavior: {
      confirmationMessage: "**Success!** Your request has been submitted."
    }
  }
}

confirmationMessageFormat

Type: "markdown" | "html" | "text" Default: "markdown"

Format of the confirmation message. Controls how the message is parsed and rendered.

Options:

"markdown" - Parses markdown syntax (bold, italic, links, etc.)
"html" - Renders HTML tags
"text" - Plain text only, no formatting

Example:

{
  behavior: {
    postClickBehavior: {
      confirmationMessage: "<strong>Success!</strong> Request submitted.",
      confirmationMessageFormat: "html"
    }
  }
}

confirmationMessageAlignment

Type: "left" | "center" | "right" Default: "center"

Horizontal alignment of the confirmation message text.

CSS Classes Applied:

"left" → justify-start
"center" → justify-center
"right" → justify-end

Example:

{
  behavior: {
    postClickBehavior: {
      confirmationMessage: "Appointment scheduled for March 15, 2025 at 2:00 PM",
      confirmationMessageAlignment: "right"
    }
  }
}

confirmationMessageColor

Type: string (CSS color value) Default: Green ("text-green-600" in light mode, "text-green-400" in dark mode)

Color of the confirmation message text. Accepts any valid CSS color value.

Examples:

Hex: "#10b981"
RGB: "rgb(16, 185, 129)"
Named: "green"
Tailwind (not recommended): "text-purple-600"

Example:

{
  behavior: {
    postClickBehavior: {
      confirmationMessage: "Premium feature activated!",
      confirmationMessageColor: "#8b5cf6"  // Purple
    }
  }
}

confirmationIcon

Type: ActionIcon Default: DEFAULT_CONFIRMATION_ICON (green checkmark SVG)

Icon to display alongside the confirmation message. Supports SVG strings, URLs, or emoji.

Icon Types:

SVG Icon:

{
  type: "svg",
  content: `<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
    <path d="M8 1.5a6.5 6.5 0 100 13 6.5 6.5 0 000-13z"/>
  </svg>`
}

Emoji Icon:

{
  type: "emoji",
  content: "❤️"
}

URL Icon:

{
  type: "url",
  content: "https://example.com/icon.png"
}

Default Icon (green checkmark):

{
  type: "svg",
  content: `<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
    <path d="M8 1.5a6.5 6.5 0 100 13 6.5 6.5 0 000-13zm2.854 4.854l-3.5 3.5a.5.5 0 01-.708 0l-1.5-1.5a.5.5 0 11.708-.708L7 8.793l3.146-3.147a.5.5 0 01.708.708z" />
  </svg>`
}

Note: All icons are rendered at 16px × 16px.

showIcon

Type: boolean Default: true (when icon is provided or using default)

Controls whether the confirmation icon is displayed.

Behavior:

showIcon: true (or undefined) with custom icon → show custom icon
showIcon: true (or undefined) without custom icon → show default checkmark
showIcon: false → hide icon entirely (text-only confirmation)

Example:

{
  behavior: {
    postClickBehavior: {
      confirmationMessage: "Request received",
      showIcon: false  // Text only, no icon
    }
  }
}

Complete Example

{
  id: "subscribe",
  label: "Subscribe to Newsletter",
  action: { type: "send_event", eventName: "newsletter_subscribe" },
  behavior: {
    oneTimeUse: true,
    postClickBehavior: {
      removeOnClick: true,
      confirmationMessage: "**Thank you!** You've been subscribed to our newsletter.",
      confirmationMessageFormat: "markdown",
      confirmationMessageAlignment: "center",
      confirmationMessageColor: "#10b981",
      confirmationIcon: { type: "emoji", content: "✅" },
      showIcon: true
    }
  }
}

ActionStyle

The ActionStyle interface controls the visual appearance of action buttons. All properties are optional.

Properties

size

Type: "small" | "medium" | "large" Default: "medium"

Controls the button size. Affects padding, font size, and icon dimensions.

Example:

{
  id: "large-button",
  label: "Get Started",
  action: { type: "open_url", url: "https://example.com" },
  style: {
    size: "large"
  }
}

backgroundColor

Type: string (CSS color value) Default: Theme default (light gray)

Background color of the button. Accepts any valid CSS color value.

Example:

{
  style: {
    backgroundColor: "#10b981"  // Green
  }
}

textColor

Type: string (CSS color value) Default: Contrast color based on background

Text and label color. Automatically adjusts for readability if not specified.

Example:

{
  style: {
    backgroundColor: "#10b981",
    textColor: "#ffffff"
  }
}

iconColor

Type: string (CSS color value) Default: Inherits from textColor

Icon color. If not specified, uses the same color as text.

Example:

{
  style: {
    backgroundColor: "#10b981",
    textColor: "#ffffff",
    iconColor: "#d1fae5"  // Lighter green for icon
  }
}

hoverBackgroundColor

Type: string (CSS color value) Default: Slightly darker/lighter than backgroundColor

Background color when hovering over the button.

Example:

{
  style: {
    backgroundColor: "#10b981",
    hoverBackgroundColor: "#059669"  // Darker green on hover
  }
}

disabledBackgroundColor

Type: string (CSS color value) Default: Gray

Background color when the button is disabled.

Example:

{
  style: {
    disabledBackgroundColor: "#e5e7eb"
  }
}

borderRadius

Type: string (CSS value) Default: "8px"

Border radius for rounded corners. Accepts any valid CSS border-radius value.

Example:

{
  style: {
    borderRadius: "4px"   // Slightly rounded
  }
}

{
  style: {
    borderRadius: "50%"   // Fully rounded (pill shape)
  }
}

Border Properties

Action buttons support both shorthand and granular border styling. The border properties follow CSS conventions and provide flexible styling options.

border (shorthand)

Type: string (CSS border shorthand) Default: "none"

Shorthand property for setting border width, style, and color in one value. If specified, this takes precedence over granular border properties.

Format: "[width] [style] [color]"

Examples:

{
  style: {
    border: "2px solid #e5e7eb"
  }
}

{
  style: {
    border: "3px dashed #10b981"
  }
}

borderWidth (granular)

Type: string (CSS border-width value) Default: "0" (when using granular properties)

Border width. Works with borderColor and borderStyle to construct the border.

Example:

{
  style: {
    borderWidth: "2px",
    borderColor: "#10b981",
    borderStyle: "solid"
  }
}

borderColor (granular)

Type: string (CSS color value) Default: "transparent" (when using granular properties)

Border color. Works with borderWidth and borderStyle.

Example:

{
  style: {
    borderWidth: "1px",
    borderColor: "#cbd5e1"
    // borderStyle defaults to "solid"
  }
}

borderStyle (granular)

Type: string (CSS border-style value) Default: "solid" (when using granular properties)

Border style. Common values: "solid", "dashed", "dotted", "double".

Example:

{
  style: {
    borderWidth: "2px",
    borderColor: "#10b981",
    borderStyle: "dashed"
  }
}

Border Property Precedence

The border properties follow a specific precedence hierarchy:

If border (shorthand) is provided: Uses it directly, ignores granular properties
If any granular property exists: Constructs border from:
- borderWidth (defaults to “0”)
- borderStyle (defaults to “solid”)
- borderColor (defaults to “transparent”)
Otherwise: Sets border to “none”

Precedence Examples:

// Shorthand takes precedence
{
  style: {
    border: "3px dotted red",
    borderWidth: "1px",  // Ignored
    borderColor: "blue"  // Ignored
  }
}
// Result: "3px dotted red"

// Granular properties combine
{
  style: {
    borderWidth: "2px",
    borderColor: "#10b981"
    // borderStyle defaults to "solid"
  }
}
// Result: "2px solid #10b981"

// Partial granular properties use defaults
{
  style: {
    borderWidth: "1px"
    // borderColor defaults to "transparent"
    // borderStyle defaults to "solid"
  }
}
// Result: "1px solid transparent"

Complete ActionStyle Example

{
  id: "styled-action",
  label: "Confirm Booking",
  icon: { type: "emoji", content: "✅" },
  action: {
    type: "send_event",
    eventName: "booking_confirmed"
  },
  style: {
    size: "large",
    backgroundColor: "#10b981",
    textColor: "#ffffff",
    iconColor: "#d1fae5",
    hoverBackgroundColor: "#059669",
    disabledBackgroundColor: "#e5e7eb",
    borderRadius: "8px",
    border: "2px solid #059669"
  }
}

ActionsConfig Container Properties

The ActionsConfig interface controls the layout and positioning of the action button group. These properties affect all buttons in the group.

Properties

position

Type: "bottom" Default: "bottom"

Vertical position of the action button group relative to the message content. Currently only "bottom" is supported (Phase 1 limitation).

Note: This property is fixed to "bottom" and doesn’t need to be specified in most cases.

alignment

Type: "left" | "center" | "right" Default: "center"

Horizontal alignment of action buttons within the message.

Example:

{
  position: "bottom",
  alignment: "left",
  actions: [
    { id: "action1", label: "Yes", action: { type: "send_event", eventName: "confirm" } },
    { id: "action2", label: "No", action: { type: "send_event", eventName: "cancel" } }
  ]
}

spacing

Type: string (CSS gap value) Default: "8px"

Gap between action buttons. Accepts any valid CSS gap value.

Example:

{
  alignment: "center",
  spacing: "16px",  // Larger gap between buttons
  actions: [
    { id: "action1", label: "Option A", action: { type: "send_query", queryText: "A" } },
    { id: "action2", label: "Option B", action: { type: "send_query", queryText: "B" } },
    { id: "action3", label: "Option C", action: { type: "send_query", queryText: "C" } }
  ]
}

Complete ActionsConfig Example

{
  position: "bottom",
  alignment: "right",
  spacing: "12px",
  actions: [
    {
      id: "confirm",
      label: "Confirm",
      icon: { type: "emoji", content: "✅" },
      action: { type: "send_event", eventName: "confirmed" },
      style: {
        backgroundColor: "#10b981",
        textColor: "#ffffff",
        border: "2px solid #059669"
      }
    },
    {
      id: "cancel",
      label: "Cancel",
      icon: { type: "emoji", content: "❌" },
      action: { type: "send_event", eventName: "cancelled" },
      style: {
        backgroundColor: "#ef4444",
        textColor: "#ffffff",
        border: "2px solid #dc2626"
      }
    }
  ]
}

Action Buttons Demo - Interactive examples
Action Button Confirmations Demo - PostClickBehavior examples
Message Interceptor - How to add actions to messages
Widget Events - Listening to action events

Actions Configuration

Overview

Action Types

Quick Example

Complete Reference

ActionBehavior

Properties

oneTimeUse

disableAllOnClick

expiresAfterTurns

disabled

disabledReason

postClickBehavior

Property Interactions

oneTimeUse + disableAllOnClick

oneTimeUse with send_query actions

expiresAfterTurns with auto-outdating

Runtime disabledReason vs. config disabledReason

Complete Example

PostClickBehavior

Properties

removeOnClick

confirmationMessage

confirmationMessageFormat

confirmationMessageAlignment

confirmationMessageColor

confirmationIcon

showIcon

Complete Example

ActionStyle

Properties

size

backgroundColor

textColor

iconColor

hoverBackgroundColor

disabledBackgroundColor

borderRadius

Border Properties

border (shorthand)

borderWidth (granular)

borderColor (granular)

borderStyle (granular)

Border Property Precedence

Complete ActionStyle Example

ActionsConfig Container Properties

Properties

position

alignment

spacing

Complete ActionsConfig Example

Related Documentation