Resultados visuales de herramientas

En el widget de voz web, una herramienta puede mostrar su resultado en pantalla, además de hacer que el agente hable sobre él: una lista de productos con precios, una tabla de pedidos o un calendario de fechas disponibles. A veces, se las denomina herramientas del cliente. La lógica permanece en tu API; el widget solo dibuja lo que recibe.

Los resultados visuales solo aparecen en el Web Voice Widget. Las llamadas telefónicas, el chat web y los canales de mensajería no se ven afectados; allí, el agente responde a partir de la misma respuesta de la herramienta, como de costumbre.

Cómo funciona

1. El agente llama a una de tus herramientas personalizadas durante una conversación de voz en el widget.
2. Tu API incluye un objeto client_side_data en su respuesta JSON.
3. El widget dibuja client_side_data y lee en voz alta su audioResponse.text.
4. El agente también recibe la respuesta completa, como lo haría con cualquier herramienta.

No hay ninguna configuración que active esta función: cualquier herramienta personalizada cuya respuesta contenga client_side_data funciona de esta manera.

El código de incorporación del widget, que se encuentra en las URLs de integración del agente, carga los renderizadores (client-tool-types.js y client-tool-renderers.js) junto con el widget en sí (voice-assistant-widget.js). En el fragmento, esas tres rutas de script comienzan con /static/. Cuando incorpores el widget en tu propio sitio, agrégales como prefijo la dirección de tu instancia de VirtuAI, como ya ocurre con la línea de la hoja de estilo; de lo contrario, el navegador los buscará en tu sitio. Consulta Widget de voz web para ver el fragmento completo.

Formato de la respuesta

{
  "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"
    }
  }
}

Campo	Qué hace
toolType	El diseño que se dibuja. Consulta la tabla que aparece más abajo.
audioResponse.text	El texto que el navegador lee en voz alta cuando aparece el resultado.
uiData	Los datos que se dibujan. Su estructura depende de toolType.
metadata.title, metadata.subtitle	Los encabezados que se muestran sobre el resultado.

Las demás claves de tu respuesta, como response en el ejemplo anterior, son el resultado habitual de la herramienta para el agente.

Diseños

toolType	Dibuja	Campos de uiData
searchResults	Una lista de resultados con vínculos.	query, totalResults, results[] con title, description, url, image, score
productList	Una cuadrícula de productos.	category, products[] con name, description, price, currency, rating, availability, image, url
datePicker	Un calendario mensual para elegir una fecha.	purpose, availableDates[], blockedDates[], selectedDate
dataTable	Una tabla que, de manera opcional, permite búsquedas y ordenamiento.	headers[], rows[][], searchable, sortable, pagination
contactCard	Una tarjeta de contacto.	name, title, company, email, phone, address, avatar, socialLinks[] con platform y url

Cualquier otro toolType se muestra en una vista genérica: el metadata.title y el uiData como JSON con formato. Usa uno de los cinco diseños anteriores para todo lo que vayan a ver los clientes.

Consejo

Mantén audioResponse.text breve y conversacional, y deja que la pantalla muestre los detalles. Leer en voz alta una tabla de diez filas no le sirve a nadie.