Skip to content
VirtuAIVirtuAI Docs

Visual tool results

In the web voice widget, a tool can show its result on screen as well as have the agent talk about it: a list of products with prices, a table of orders, a calendar of available dates. These are sometimes called client-side tools. The logic stays in your API; the widget only draws what it is sent.

Visual results appear only in the Web Voice Widget. Phone calls, web chat and messaging channels are not affected; the agent there answers from the same tool response as usual.

How it works

Section titled “How it works”
  1. The agent calls one of your custom tools during a voice conversation in the widget.
  2. Your API includes a client_side_data object in its JSON response.
  3. The widget draws client_side_data and reads its audioResponse.text aloud.
  4. The agent also receives the whole response, as it would for any tool.

No setting turns this on: any custom tool whose response contains client_side_data works this way.

The widget embed code from the agent’s integration URLs loads the renderers (client-tool-types.js and client-tool-renderers.js) along with the widget itself (voice-assistant-widget.js). In the snippet, those three script paths start with /static/. When you embed the widget on your own site, prefix them with your VirtuAI address, as the stylesheet line already is; otherwise the browser looks for them on your site. See Web voice widget for the full snippet.

Response format

Section titled “Response format”
{
  "response": "Found 3 running shoes under $100.",
  "client_side_data": {
    "toolType": "productList",
    "audioResponse": {
      "text": "I found three running shoes under one hundred dollars."
    },
    "uiData": {
      "category": "Running shoes",
      "products": [
        {
          "name": "Trail Runner 2",
          "price": 89.99,
          "currency": "USD",
          "rating": 4.5,
          "availability": "In stock",
          "image": "https://example.com/img/trail-runner-2.jpg",
          "url": "https://example.com/p/trail-runner-2"
        }
      ]
    },
    "metadata": {
      "title": "Running shoes",
      "subtitle": "Under $100"
    }
  }
}
Field What it does
toolType Which layout to draw. See the table below.
audioResponse.text Text the browser reads aloud when the result appears.
uiData The data to draw. Its shape depends on toolType.
metadata.title, metadata.subtitle Headings shown above the result.

The other keys in your response, such as response above, are ordinary tool output for the agent.

Layouts

Section titled “Layouts”
toolType Draws uiData fields
searchResults A list of results with links. query, totalResults, results[] with title, description, url, image, score
productList A product grid. category, products[] with name, description, price, currency, rating, availability, image, url
datePicker A month calendar to pick a date. purpose, availableDates[], blockedDates[], selectedDate
dataTable A table, optionally searchable and sortable. headers[], rows[][], searchable, sortable, pagination
contactCard A contact card. name, title, company, email, phone, address, avatar, socialLinks[] with platform and url

Any other toolType is shown in a generic view: the metadata.title and the uiData as formatted JSON. Use one of the five layouts above for anything customers will see.