Skip to content
UX Guide

Actions

Introduction to Actions

Actions allow the AI-powered chatbox to execute specific functions within your website. They are essential for improving user experience, helping users navigate complex sites, autofill forms, or provide direct assistance when the website’s UX isn’t intuitive enough.

By defining actions, you enable the chatbox to perform meaningful tasks instead of merely responding with text-based suggestions.

Importing Required Modules

To start using actions, ensure you have the necessary imports:

import { UxGuide, ActionParameter } from "ux-guide";


const uxGuide = new UxGuide();

Defining Actions

An action consists of:

  • A unique identifier (e.g., "bug-report")
  • A trigger condition (a description of when it should execute)
  • A list of parameters (if needed)
  • A callback function that defines the action’s behavior

Let’s start with a simple example.

Example: Bug Report Action

The following action is triggered when a user reports a bug. It displays an alert confirming the report.

uxGuide.addAction(
  "bug-report",
  "Execute when the user reports a bug on this website",
  [],
  (chat) => {
    alert("We're sorry for the inconvenience. The issue has been reported!");
  }
);

This is useful but could be improved by gathering additional feedback from the user.

Adding Parameters to Actions

Parameters allow the chatbox to extract useful information from conversations and pass them into actions. Let’s extend our bug report action by adding a feedback parameter.

uxGuide.addAction(
  "bug-report",
  "Execute when the user reports a bug on this website",
  [
    new ActionParameter("feedback", "string", "Detailed description of the user's problem", true),
  ],
  (chat, { feedback }) => {
    console.warn(`User reported a bug: ${feedback}`);
    alert("We're sorry for the inconvenience. The issue has been reported!");
  }
);

Understanding ActionParameter

Each parameter is defined using the ActionParameter class:

  1. Name - The key used to reference this parameter.
  2. Type - The expected data type ("string", "number", or "boolean").
  3. Description - A short explanation of what this parameter represents.
  4. Optionality - Determines if the parameter is required (default: true). If set to false, the AI will only provide the parameter if it can reliably extract it from the conversation.

Now, let’s extend our action further.

Example: Adding a Frustration Rating

We can add an optional frustrationScale parameter to measure user frustration on a scale from 1 to 10.

uxGuide.addAction(
  "bug-report",
  "Execute when the user reports a bug on this website",
  [
    new ActionParameter("feedback", "string", "Detailed description of the user's problem"),
    new ActionParameter("frustrationScale", "number", "Frustration rating (1-10)", false),
  ],
  (chat, { feedback, frustrationScale = 0 }) => {
    const frustrationPercentage = (frustrationScale / 10).toFixed(2);
    console.warn(`User reported a bug. Frustration: ${frustrationPercentage}%. Description: ${feedback}`);
    chat.info("We're sorry for the inconvenience. The issue has been reported!");
  }
);

Using chat.info

Instead of an alert, we now use chat.info(), which adds a message directly inside the chatbox, providing a more seamless user experience.

Enhancing User Interaction with Forms

What if the user wants to refine their feedback before submitting it? We can use chat.form() to allow modifications before final submission.

uxGuide.addAction(
  "bug-report",
  "Execute when the user reports a bug on this website",
  [
    new ActionParameter("feedback", "string", "Detailed description of the user's problem"),
    new ActionParameter("frustrationScale", "number", "Frustration rating (1-10)", false),
  ],
  (chat, { feedback, frustrationScale }) => {
    chat.form("Bug Report", (form) => {
      const feedbackInput = form.input().defaultContent(feedback);
      const frustrationInput = form.input().defaultContent(frustrationScale).type("number");


      form.button("Submit").onClick(() => {
        const updatedFrustration = (frustrationInput.value || 0) / 10;
        console.warn(`User submitted a bug report. Frustration: ${(updatedFrustration * 100).toFixed(2)}%. Description: ${feedbackInput.value}`);
        chat.info("Thank you! Your bug report has been submitted.");
      });
    });
  }
);

How chat.form() Works:

  1. A form appears inside the chatbox.
  2. The user can modify the feedback and frustrationScale before submitting.
  3. When the Submit button is clicked, the updated values are logged and a confirmation message is displayed.

Adding Voice Input (Optional)

To make reporting even easier, let’s add voice input using the Web Speech API:

uxGuide.addAction(
  "bug-report",
  "Execute when the user reports a bug on this website",
  [
    new ActionParameter("feedback", "string", "Detailed description of the user's problem"),
    new ActionParameter("frustrationScale", "number", "Frustration rating (1-10)", false),
  ],
  (chat, { feedback, frustrationScale }) => {
    chat.form("Bug Report", (form) => {
      const feedbackInput = form.input().defaultContent(feedback);
      const frustrationInput = form.input().defaultContent(frustrationScale);


      let recognition;
      const startVoiceRecording = () => {
        recognition = new (window.SpeechRecognition || window.webkitSpeechRecognition)();
        recognition.lang = "en-US";
        recognition.continuous = false;
        recognition.interimResults = false;


        recognition.onresult = (event) => {
          feedbackInput.value = event.results[0][0].transcript;
        };


        recognition.onerror = (error) => {
          console.error("Speech recognition error:", error);
        };


        recognition.start();
      };


      form.button("🎤 Speak Feedback").onClick(startVoiceRecording);
      form.button("Submit").onClick(() => {
        console.warn(`User reported a bug: ${feedbackInput.value}`);
        chat.info("Thank you! Your bug report has been submitted.");
      });
    });
  }
);

Conclusion

Actions are a powerful way to extend your AI chatbox’s capabilities. By utilizing parameters, embedded messages, and forms, you can make your chatbox genuinely useful for users navigating your website. Adding optional voice input further enhances accessibility.

Now, go ahead and build intuitive, AI-powered interactions!