Web Chat Page Actions

Overview

Use Fill Form Field and Press Page Button to let a Conversational Agent request updates on the page hosting its Web Chat widget. Both activities are Web Chat only and appear under Web Automation exclusively in the agent's Tools picker, not in the canvas toolbox.

User message → Conversational Agent → client-action tool
             → Web Chat widget → host page handler

The host page performs the actual operation. It must validate requests and update its own form or application state. These tools do not require a customer webhook to fill fields or request button actions.

Configure the agent's tools

1. Connect a Web Chat Trigger to a Conversational Agent.
2. Open the agent's Tools picker and add Fill Form Field, Press Page Button, or both from Web Automation.
3. Set every activity-specific input to FromAI for direct delivery. All these inputs are required strings.
4. Give the agent instructions matching the host's field and button names, when to request each action, and how to describe any host confirmation step. For consent fields, instruct the agent to ask explicitly before requesting an update.

Shared tool settings

Property	Type or choices	Purpose
Tool Description	string	Describe when the model should invoke the tool.
Tool Acknowledgement	Inherit, Override, Disabled	Usual inherited tool acknowledgement setting. Client-action calls do not speak an acknowledgement, even when configured.
Tool Acknowledgement Message	string	Usual inherited acknowledgement message; it is not spoken for client-action calls.
Barge-in Mode	NotAllowed, Cancel, ContinueInBackground	Usual inherited setting for tool behavior during user interruption.

The designer does not show Is Tool, Wait All Incoming, or On Error for these activities. The standard Error Message output is available for a failed run.

Input binding and delivery

When every activity-specific input is FromAI, the pipeline builds the result JSON itself and does not resume the workflow. A blank or missing argument returns {"error":"Missing argument <name>"} using Field, Value, or Button as the argument name. This error is not relayed to the host page.

Literal or expression bindings use the normal tool lane and emit the same client-action JSON shape. They do not use the direct-delivery path.

Embed the widget

Replace the host and chat ID placeholders with your deployment values.

<div id="assistant" style="height:420px"></div>
<script src="https://<your-intellibuddies-host>/assets/widget.js"></script>
<script>
  ChatWidget.init(
    'https://<your-intellibuddies-host>/chat/<your-chat-id>',
    { inline: '#assistant' }
  );
</script>

The inline option mounts the conversation and input box inside the selected element. Without it, the widget uses the floating bubble layout. In the inline layout, provide your own AI and recording disclosures where appropriate because the usual footer is not displayed.

Describe the page

Supply field and action descriptions through setContext so the assistant knows the names to use.

ChatWidget.setContext({
  form: {
    id: 'registration',
    fields: [
      { name: 'firstName', label: 'First name', type: 'text', required: true },
      { name: 'dob', label: 'Date of birth', type: 'date', required: true }
    ],
    actions: [{ name: 'submit', label: 'Submit registration' }]
  }
});

This describes the form; it does not automatically send values already entered on the page. Calling setContext also establishes the host page's origin for delivery from the chat frame. Declaring fields and actions does not make the widget enforce an allowlist.

Handle client actions

Register a handler that routes the result to your application's own functions:

ChatWidget.onClientAction(function (a) {
  if (a.action === 'fillFormField') {
    // a.payload = { ClientAction, Field, Value, Status }
    fillField(a.payload.Field, a.payload.Value);
  }
  if (a.action === 'pressButton') {
    // a.payload = { ClientAction, Button, Status }
    requestPageAction(a.payload.Button);
  }
});

fillField and requestPageAction are functions you implement, not widget APIs. The widget forwards the result unchanged. The chat iframe checks that the result is JSON with a ClientAction property; the widget does not validate payload fields, allowlist button names, or open a confirmation dialog.

Your handler should:

• Reject unknown field and action names using an explicit allowed list.
• Convert string values to the target field's expected representation, such as a date, checkbox state, or selected option, and run normal form validation.
• Update application state as well as the visible control. For React, Vue, or Angular forms, use the framework's setter or the appropriate native setter and input/change events.
• Check required fields and implement any confirmation or actual-user-click requirement before executing actions such as submission.

Host-controlled confirmation

There is no confirm property on either activity, and the widget does not enforce confirmation. You may add confirm: true to your own action metadata as a convention, but your handler must read and enforce it. A handler that ignores the metadata can execute a requested action without extra confirmation.

For example, your requestPageAction('submit') implementation can validate the form, show a review panel, and wait for the user's own Confirm click. The agent's instructions should explain this behavior to the user. Instructions and status text alone do not enforce it.

Understand the result

Both tools expose string outputs describing what was sent. See their activity references for exact payloads and status strings.

Calls are fire-and-forget. The host's acceptance or rejection is not returned to the agent. A sent field value may fail page validation; a requested button action may be rejected or await confirmation. Do not interpret the tool's Status as evidence that the form was updated or submitted.

Fill Form Field sends one field per call. Multiple field updates require multiple calls. Conversation quality depends on the agent's instructions and its model's ability to call tools.

Verify your integration

Test a valid field update, unknown names, invalid values, required-field validation, and the host's confirmation flow. Check that the actual application state changes and that the agent does not claim completion based only on dispatch. Also verify missing-argument handling and any Literal or expression bindings you use.