Guide: Setting up an API Action

This guide will walk through setting up an API Action.

To begin, click “Actions” on the left navigation.

💡 The action can be saved as a draft at any point by pressing the back arrow at the top left of the page.

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 API" to proceed to the next step, where this action's communication with the backend service will be set up.

Step 2 - Configure API

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.

Inputs can be sourced from both users via a form (Form Field) or as custom data attributes via the frontend (User and Secret Attributes).

Adding Inputs

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.

Input Source - Choose where the input will receive its value from.

• Form Field - The input value will be populated through an input form that is presented to the user when the action is triggered
• User Attribute - The input value will be populated from the custom user attributes that are specified in the user identification call in the Brainfish Widget SDK.
• Secret Attribute - The input value will be populated from the secret attributes that are provided in the Brainfish Widget SDK (see below for more details).

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.

Form Field Inputs

Form Field values are populated through an input form that is presented to the user when the action is triggered. The form that will be shown to the user can be previewed by clicking "Form Preview" in the top bar of the Input management dialogue.

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

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.

User Attribute Inputs

User Attribute values are populated using the custom user attribute values provided in the widget initialisation JavaScript snippet. For example, if the following attributes are specified:

Brainfish.Widgets.identify({
  userId: "<unique id>",
  email: "john.doe@example.com",
  teamId: "team_123",
  subscription: "premium",
  isAdmin: true,
});

Attribute Type - This is used to validate the attribute value before passing it to the API call. Attributes values can be text (string), numerical (number) or true/false (boolean).

Secret Attribute Inputs

Secret attributes allow you to securely pass sensitive data (like access tokens or secret values) to the Brainfish platform via the widget, without exposing it to the client-side user. These attributes are encrypted and are only accessible by the backend when executing API actions.

How to Use Secret Attributes

Brainfish.Widgets.setSecretAttributes(encryptedString);

Encrypting Secret Attributes

✅ Recommended: Use Brainfish Secure API

We provide a secure API endpoint to encrypt your attributes using the secret token generated in your team's Security settings.

Example Request:

curl --location 'https://app.brainfi.sh/api/auth.encryptAttributes' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{REPLACE_WITH_YOUR_API_KEY}}' \
--data '{
    "attributes": {
        "accessToken": "xxxxxx",
        "secretValue": "zzzzzz"
    }
}'

Example Response:

{
    "data": {
        "encryptedAttributes": "x23#!@#$%^&*()_+"
    }
}

🛠️ Alternative: Use Your Own Encryption

If you’d prefer to encrypt the attributes yourself, you can use the jose library.

Javascript Example:

import * as jose from 'jose';

const encryptedAttributes = await new jose.CompactEncrypt(
  new TextEncoder().encode(JSON.stringify({ accessToken: "xxxxxx", secretValue: "zzzzzz" }))
)
  .setProtectedHeader({ alg: "dir", enc: "A256GCM" })
  .encrypt(Buffer.from(YOUR_SECRET_TOKEN_FROM_SECURITY_SETTINGS, "hex"));

Python Example:

from jose import jwe

import json

payload = json.dumps({ "accessToken": "xxxxxx", "secretValue": "zzzzzz" })
encrypted = jwe.encrypt(
    payload,
    YOUR_SECRET_TOKEN_FROM_SECURITY_SETTINGS,
    algorithm='dir',
    encryption='A128GCM'
)

NOTE: YOUR_SECRET_TOKEN_FROM_SECURITY_SETTINGS is your secret token found in the Team > Security Settings section in Brainfish.

Final Step

Once you have the encrypted string (either via API or custom method), pass it to the widget:

Brainfish.Widgets.setSecretAttributes(encryptedAttributes);

This ensures your sensitive values are securely handled during any widget-initiated API actions.

Managing Inputs

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.

Building the HTTP Request

The HTTP request builder allows configuration of the API call and injection of the inputs that have been set up in the above steps.

Testing the request

The API request can be tested at any time by clicking the "Test API" button at the bottom right of the request builder. The Test API dialogue will appear. Input values for testing can be provided for all Form inputs in the "Add test values" section. When "Submit" is pressed, the API request will be triggered with the test values injected. The response body and headers can be viewed in the "Test output" section.

Previewing the action in an agent

⚠️ Make sure to press "Save" before testing in the Agent, otherwise the action may not work.

The action can be previewed in an agent in the "Test Agent Action" panel on the right hand side of the screen. There are some suggested questions to try or alternative queries can be entered in the search input.

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.