In-app assistant

Overview

The YuAskMe chat widget normally talks to your customers. In operator mode it works for your own team instead: it sits on every page of your app and turns requests like “show me today's sales” or “how is the business doing?” into actions your app performs.

• You define the actions. Each one has a name, a description the AI reads, and optional parameters.
• YuAskMe decides which action fits the request and extracts the parameters (a date range, a customer name, an amount) from the message.
• Your code runs the action in the browser, as the signed-in user, and returns a message the assistant replies with.

Example: POSIBLI

POSIBLI, the point-of-sale and operations platform by Xybersoft, ships YuAskMe as its YuAskMe Assistant: an in-app assistant that navigates the dashboard and pre-fills forms from plain-language requests. It's available on every signed-in page and offers around 45 actions across sales, inventory, procurement, and invoicing.

Every action checks the user's permissions first: if someone can't open a page in POSIBLI, the assistant can't open it for them either.

How it works

1. Your server publishes a list of actions (the manifest) to your YuAskMe workspace.
2. Your app loads the YuAskMe widget with operator mode on.
3. Your app registers a handler in the browser for each action name.
4. A staff member types a request. YuAskMe matches it to an action, extracts the parameters, and the widget calls your handler with them.
5. Your handler does the work (navigate, read data, open a form) and returns a message. The assistant shows it in the chat.

Everything below belongs to one YuAskMe workspace: the actions, the MCP token, the knowledge base, and the widget's data-identifier. So start by creating a workspace for the assistant (step 0). The widget script URL and the sync URL come from the YuAskMe team when you turn on operator mode.

Setup checklist

1. Create a workspace for the assistant and note its identifier (step 0).
2. Turn on MCP for that workspace in Settings → MCP Server and generate a token. Keep it on your server only.
3. Add a knowledge base about your app or business, so the assistant can answer questions, not just run actions (see Questions vs actions).
4. Declare your actions and sync them (step 1). Sync again whenever the list changes.
5. Embed the widget with operator mode and an agent theme (step 2).
6. Register a handler for every action (step 3).
7. Test with a command (“open the sales report”), a question (“how do refunds work?”), and a draft (“invoice Juan ₱500”). Check the browser console for missing handlers.

0. Create a workspace

A workspace is one assistant with its own knowledge base, actions, settings, and MCP token. Give the in-app assistant a workspace of its own, so its actions and knowledge don't mix with your customer chatbot.

New to YuAskMe

1. Sign up for a business account at yuask.me/business/register. Your account starts with one workspace, named after your business.

Already have an account

1. In the dashboard, open Workspaces and click Add Workspace.
2. Enter a Workspace Name, for example “Back-office assistant”, and create it.
3. Switch to the new workspace with the workspace selector at the top of the dashboard. Everything you set up next (MCP token, knowledge base, Intent Config) applies to the workspace that's selected.

Find the workspace identifier

In Workspaces, click Edit on the workspace. The Identifier field (for example la-hacienda) is set from the name when the workspace is created and never changes. You'll use it as the widget's data-identifier.

1. Declare your actions

Each action has a name, a description written for the AI (say when to use it), and optional params. Good descriptions matter: they're how the assistant picks the right action.

const actions = [
  {
    name: "show_sales_report",
    description: "Shows the sales performance report, optionally filtered to a time period",
    params: [
      {
        name: "period",
        type: "string",
        description: "One of: today, yesterday, last7, last30, month, lastMonth, year. Omit for the default view.",
        required: false,
      },
    ],
  },
  {
    name: "create_invoice",
    description: "Opens a new invoice pre-filled with the given customer, line description, and amount, for the user to review and save",
    params: [
      { name: "customer", type: "string", description: "Customer name to bill", required: false },
      { name: "description", type: "string", description: "What the invoice line is for", required: false },
      { name: "amount", type: "number", description: "Line item amount", required: false },
    ],
  },
];

Publish the list from your server, for example at startup:

await fetch(`${process.env.YUASKME_NODE_URL}/host-actions/sync`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ mcpToken: process.env.YUASKME_MCP_TOKEN, actions }),
});

2. Embed the widget in operator mode

Load the widget script once, on every signed-in page:

<script
  src="YOUR_WIDGET_SCRIPT_URL"
  data-identifier="your-workspace"
  data-operator-mode="true"
  data-theme="agent-5"
  data-retain-conversation="true"
  data-customer-uid="STAFF_USER_ID"
  data-color="#2c3e64"
  async
></script>

Choosing a theme

Operator mode is built for the agent themes. They float over your app and can mark what the assistant is talking about on the page.

To point at something on the page, return highlight from a handler, e.g. { message: "Here it is.", highlight: { targets: [element], label: "Business plan" } }. The agent theme marks those elements; the highlight never leaves the page.

3. Handle the actions

Once the script has loaded, register a handler for each action with window.yuaskmeOnAction(name, handler). The handler receives the extracted parameters and returns { message }, which the assistant shows in the chat.

script.onload = () => {
  window.yuaskmeOnAction("show_sales_report", ({ period }) => {
    navigate(period ? `/reports/sales?period=${period}` : "/reports/sales");
    return { message: "Showing the sales report." };
  });

  window.yuaskmeOnAction("create_invoice", ({ customer, description, amount }) => {
    const q = new URLSearchParams();
    if (customer) q.set("customer", String(customer));
    if (description) q.set("description", String(description));
    if (amount != null) q.set("amount", String(amount));
    navigate(`/invoices/new?${q}`); // opens the form; staff review and click Save
    return { message: "Opening a new invoice with those details. Review and save when ready." };
  });
};

Only register the actions the signed-in user is allowed to use. If the assistant picks an action you didn't register, return { error: "Not available for this account." }.

Kinds of actions

Navigate

Open a page, optionally filtered (show_inventory, show_low_stock_items). Safe to run immediately, since nothing changes.

Read and report

Fetch data with the user's own session and return a plain-text summary for the assistant to report. In POSIBLI:

• get_current_screen reads what's open (the page, its heading, form values, table rows, dialogs) and suggests what can be done next, so “this RFQ” or “this page” just works. Password fields are never read.
• get_business_health combines sales, inventory, procurement, and receivables into one snapshot with the items that need attention.
• analyze_rfq_quotations compares supplier quotations against the buyer's original estimate, line by line.

Draft

Open a real form pre-filled with what the assistant extracted (create_invoice, create_requisition). Your existing Save button and validation do the actual write.

Questions vs actions

In operator mode, YuAskMe first decides what kind of message it got, and only some messages reach your actions:

• Fill the knowledge base. Questions never reach your actions, so an empty knowledge base gives thin answers (“the reference information does not mention…”). Upload short, focused articles, one topic each.
• Set a complaint response. Problem reports are handled as complaints. In the workspace's Intent Config, give Complaint a fixed Response Text with your real support contact, so the assistant never improvises one.
• Write descriptions as triggers. If a request gets “I'm not sure how to do that yet”, no action matched it. Add the user's wording to the action's description and sync again.

Design rules

• Never let the assistant write data directly. Actions that create or change records open a pre-filled form for a person to review and save. A misread amount should never become a real invoice.
• Respect permissions. Gate each handler by the same permission its page requires, so the assistant can never do more than the user could.
• Compute numbers in code, not in the AI. Totals, comparisons, and flags should be calculated by your handler and returned as text, so every figure is exact.
• Report gaps honestly. If a section of data isn't available to the user, say so instead of guessing.
• Keep names in sync. Every action in the manifest needs a handler with exactly the same name.

Troubleshooting

Something unclear or out of date? Report a docs issue.