Guide: Setting up a Client Action

This guide will walk through setting up a Client Action.

To begin, click Actions on the left navigation and select Create new action > Client Action

Step 1 - Define Your Action

Action - This is the name or label for the action the user will perform. Describe the intent or outcome of the action clearly.

Example: "Submit feedback", "Get shipping status", or "Create support ticket".

💡 Click See examples for sample action names if the phrasing is uncertain.

Description (Optional) - A short summary of what this action does, useful for providing further information to the Agent about when to trigger the action. Write a simple explanation of what the action does and include some example questions or scenarios where the action should be triggered.

Example: The Order Status action provides users with updates on their current orders, including processing, shipping, and delivery information. Users can inquire about the status of their orders, expected delivery dates, and any delays.

🔄 Click Auto-generate to fill this field based on the action name.

Once these fields are completed, click Configure your inputs to proceed to the next step, where this action's communication with the backend service will be set up.

Step 2 - Configure your inputs

Inputs are values that an action needs to run. For example, if an action checks the status of an order, it may need an input for the Order ID and the Email that the order is associated with. Input values are populated through an input form that is presented to the user when the action is triggered.

Click Add Inputs to set up inputs. The Input management dialogue will appear. There will already be an empty input called New Input. Click the down arrow to expand the input options. Additional inputs can be added by pressing the "+" button at the bottom of the input list.

Input Name - Provide a name for the input (e.g. order_id). This is like a variable name for internal use and will not be shown to the user.

Required - Enable this toggle if a value for the input is always required for the action to run. This will ensure that a value is provided from the appropriate source before the action can be executed. For example, when fetching an order status, both the Order ID and User Email would be required inputs.

Input Type - This controls how the form input field will be displayed and validated.

Input Type	Description
Short Answer	Single-line text input field
Long Answer	Multi-line text input field
Date	Date picker
Dropdown	Constrain the input value to a predefined set of values
Phone	Phone number input field
Email	Email input field
Number	Number input field

Label (Optional) / Description (Optional) - Provide a user-friendly label (and optional description) to assist users in filling out the form.

💡 The input form can be previewed by clicking Form Preview in the top bar of the Input management dialogue.

Additional inputs can be added by pressing the "+" button at the bottom of the input list. Inputs can be reordered and deleted using the buttons on the right of each input block.

Once the action has been built and tested, click Apply Filter to proceed to the next step.

Step 3 - Apply Filters (Optional)

Regions - The action can be filtered to only trigger if the user is in a certain region. This field will only be visible if region segmentation is enabled.

Show on - The action can be shown on all Agents and Help Center, or specific agents can be selected along with enabling or disabling the action on Help Center by selecting values here.

Once filters have been configured, click Save & Publish to publish the action.

Step 4 - Defining the handler callback

Add the following snippet to your frontend where the Brainfish Widget is installed:

Brainfish.Widgets.registerClientActionHandler('<action_key>', async (inputs) => {
  // YOUR CUSTOM ACTION HANDLER CODE GOES HERE

  // For Example:
 
  // the action handler receives the validated inputs as an object
  const { email, phone, username } = inputs;

  // Your custom code to handle the action goes here
  // You can do anything here, for example:
  //   - calling an API directly via fetch
  //   - calling your own frontend code, library, or SDK
  //   - triggering a UI action
  const response = await fetch("/api/me", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": YourAuthService.getAuthToken(),
    },
    body: JSON.stringify({ phone, email, username }),
  });

  if (!response.ok) {
    // If the handler fails, throw an Error with a descriptive message
    throw new Error("Failed to update your account: " + await response.body());
  }

  const { updatedAt } = await response.json();

  // You have full control over the data that is returned to Brainfish
  // You only have to provide enough information so that our AI Agent can determine the outcome of the action
  return { updatedAt };

});

Brainfish.Widgets.registerClientActionHandler takes 2 arguments:

• actionKey - the action key (e.g. bf_action_xxxxxxxxxx)

• handler - a callback function that is executed when the action is triggered. The callback receives the action inputs in an inputs object with the object keys as the input names. For example, if you define an input called email_address, it will be accessible at inputs.email_address

<aside>

• handler must return an object. If handler returns anything other than an object or throws an error, the action will be treated as a failure.

• handler will timeout if it does not return a value within 5 seconds </aside>

Finding the Action key

You can retrieve the Action key from the context menu on the Actions screen by clicking Copy Action Key**.**

Step 5 - Testing

To test Client Actions, we recommend:

1. Set up a dedicated testing Agent in the platform
2. Create a new client action as outlined above except during Step 3 - Apply Filters, enable the Show on filter by selecting the testing Agent that you configured
3. Publish the action
4. Initialise the testing Agent widget and register the client action handler in a staging environment or code sandbox
5. Once testing is completed, update or remove the filter to enable the Client Action on your production Agent