Herramientas

Las herramientas amplían lo que Chat puede hacer durante una conversación. Un webhook puede obtener datos en tiempo real de un servicio externo, mientras que una herramienta de JavaScript puede ejecutar código en el navegador del comprador y realizar una acción en tu tienda online.

Nombre y descripción #

Ve a Chat > Tools y haz clic en + Add another tool para abrir el editor de herramientas. Dale a la herramienta un nombre claro y describe cuándo Chat debería usarla.

La descripción actúa como una instrucción para la IA. Sé específico sobre la situación que debe activar la herramienta. Por ejemplo:

“Cuando un cliente pregunta sobre un pedido, usa los datos de pedido disponibles en product_data para proporcionar información sobre su pedido.”

Una descripción clara ayuda a Chat a usar la herramienta correctamente y evita que la llame para preguntas no relacionadas.

Tipo de herramienta #

Elige Webhook o JavaScript en la sección Type. Webhook llama a una API HTTPS. JavaScript se ejecuta en el navegador del comprador.

Crea con Ask #

Si no deseas configurar la herramienta tú mismo, pide a Ask Clerk.io que proponga una herramienta webhook o JavaScript. Describe lo que Chat debería hacer, luego revisa y confirma el nombre propuesto, la descripción, los parámetros y la configuración antes de usarla.

Webhooks #

En Type, selecciona Webhook. Las herramientas webhook llaman a tu API HTTP. Úsalas cuando un servicio pueda proporcionar los datos o realizar la acción que Chat necesita a través de un endpoint.

Parámetros #

Define los valores que Chat necesita antes de poder ejecutar la herramienta. Chat recopila estos valores de la conversación y pregunta al visitante cualquier valor obligatorio que falte.

Para cada parámetro, define:

• Name — El nombre de la variable utilizada por el endpoint o función JavaScript.
• Type — El tipo de valor que Chat debe recopilar, como texto o un número entero.
• Description — Lo que representa el valor y qué debe preguntar Chat al visitante.

Usa los mismos nombres de parámetro en tu solicitud o código JavaScript que en la lista de parámetros. Por ejemplo, un parámetro llamado order_id debe leerse como order_id en la plantilla o función correspondiente.

Marca un parámetro como Required cuando la herramienta no pueda funcionar sin él.

Endpoint #

Configura la solicitud HTTP que Chat envía cuando se ejecuta una herramienta webhook.

Method: Elige GET, POST, PUT o DELETE, dependiendo de lo que requiera tu API.

URL: Ingresa la URL completa del endpoint. Los parámetros de consulta pueden ser estáticos o pueden usar valores recopilados de la conversación con {{parameter_name}}. Por ejemplo:

https://api.example.com/orders?email={{email}}&id={{order_number}}

Custom headers: Agrega cualquier header que requiera tu API, como tokens de autenticación o sobrescrituras de tipo de contenido.

Request body: Para solicitudes POST y PUT, ingresa el cuerpo en el formato que espera tu API. Puedes usar parámetros aquí también.

Timeout: Elige cuánto tiempo debe esperar Chat por una respuesta antes de abandonar. Las opciones disponibles van de 3 segundos a 10 minutos.

Guardar y probar #

Haz clic en Save cuando la herramienta esté lista.

Abre Test desde la barra de herramientas de la página o su menú de acciones. En la ventana emergente de prueba, ingresa valores de ejemplo para los parámetros configurados, ejecuta la prueba e inspecciona la respuesta. Cierra la ventana para volver al editor.

JavaScript #

En Type, selecciona JavaScript. Las herramientas JavaScript se ejecutan en el navegador del comprador y pueden conectar Chat con funcionalidades que ya existen en tu tienda online, como:

• agregar un producto al carrito
• leer el carrito actual
• aplicar un código de descuento
• abrir el checkout
• abrir una guía de tallas
• guardar un producto en una wishlist
• abrir un localizador de tiendas o un flujo de recogida en tienda

Estas son acciones personalizadas, no operaciones integradas. Debes conectar cada herramienta con la funcionalidad correspondiente en tu tienda online.

Parámetros #

Define los valores que Chat necesita antes de poder ejecutar la herramienta. Chat recopila estos valores de la conversación y pregunta al visitante cualquier valor obligatorio que falte.

Para cada parámetro, define:

• Name — El nombre de la variable utilizada por la función JavaScript.
• Type — El tipo de valor que Chat debe recopilar, como texto o un número entero.
• Description — Lo que representa el valor y qué debe preguntar Chat al visitante.

Usa los mismos nombres de parámetro en tu solicitud o código JavaScript que en la lista de parámetros. Por ejemplo, un parámetro llamado order_id debe leerse como order_id en la plantilla o función correspondiente.

Marca un parámetro como Required cuando la herramienta no pueda funcionar sin él. Lee los valores recopilados desde el objeto args en tu función.

Código #

Escribe una función asíncrona que la tienda online ejecuta cuando Chat llama a la herramienta. El editor proporciona a la función los argumentos recopilados y el contexto de la tienda.

Utiliza el objeto args para leer los valores definidos en Parameters. Luego llama al código de la tienda que realiza la acción, como agregar un artículo al carrito o abrir el checkout. Devuelve un resultado claro para que Chat pueda decirle al visitante lo que ocurrió.

El JavaScript exacto depende de tu tienda online. Asegúrate de que la función maneje de forma segura valores que falten, inválidos o no disponibles.

Guardar y probar #

Haz clic en Save cuando la herramienta esté lista.

Prueba las herramientas JavaScript en una tienda de prueba o de vista previa antes de ponerlas a disposición de los visitantes. Verifica tanto la acción en la tienda como el mensaje que Chat proporciona después de completar la acción.