Widgets and response mapping

Widgets turn an action result into an interactive card. Choose Call API + show widget when the card needs an API response, or Show widget when it can use fixed values and supplied inputs.

1. 1Open the Widget section of a compatible custom action.
2. 2Choose Add widget to create or select a widget, or upload a .widget file.
3. 3Review the selected widget and its declared input fields.
4. 4Connect the action data to those fields and check the preview.
5. 5Save and continue, then select channels and enable the action.

For API widgets, first run a successful API test so you can inspect the response structure. Map the response values to the widget inputs, paying attention to field names, types, nested objects, and arrays. For Show widget, define any inputs the agent should supply and keep them aligned with the widget schema.

{
  "page": {
    "title": "QwryAI deployment guide",
    "headings": ["Deploy your QwryAI agent", "Add the widget to your website", "Check the customer experience"]
  }
}

A page-help card can map its title and headings inputs from the page object. These values reflect the deployment guide used in the client-side action walkthrough. Use the actual response shape from your own API when mapping an API widget.

For a conversational Show widget action, use Collect widget fields before showing it when the agent should obtain required information first. An action with automatic triggers displays immediately: the input-collection switch is disabled, so the widget must work with the data already available. Give optional fields useful defaults and check the empty-data state.

• Test with a complete response and with missing optional values.
• Check long labels, arrays with multiple items, and an empty result.
• Verify buttons and form controls on the deployed website.
• Check the narrow mobile layout and keyboard focus order.
• If the action is automatic, test its placement and dismissal settings too.