En el generador de integraciones, los parámetros de solicitud permiten extraer datos (parámetros de conversación) de las conversaciones del agente IA y pasarlos a los extremos externos. Habrá casos en que quizás tenga que transformar o cambiar el formato de estos datos antes de enviarlos a una solicitud de API, ya sea como una consulta de URL o en el cuerpo de la solicitud. Para ello se puede usar JSONata, un potente lenguaje de consultas y transformación.
Los temas tratados en el artículo son estos:
- Cambiar el formato del valor de un parámetro de solicitud
- Ejemplos de casos de uso comunes para cambiar el formato de valores
Artículo relacionado:
Cambiar el formato del valor de un parámetro de solicitud
El formato del valor de un parámetro de solicitud se puede cambiar con JSONata.
Para cambiar el formato del valor de un parámetro de solicitud
- En el espacio de trabajo de agentes IA, en la esquina superior derecha, vaya al campo desplegable Agente IA y seleccione un agente IA.
- En el menú principal de la izquierda, haga clic en Integraciones de API.
- Seleccione o cree una integración.
- En la página Parámetros de solicitud, seleccione o cree el parámetro de solicitud cuyo formato de valor desea cambiar.
- En el campo Valor de prueba, seleccione el icono de cambio de formato del valor (
).
- En el cuadro de diálogo Reformatear valor, en el campo Reformateo de JSONata, use JSONata para transformar o cambiar el formato del valor asociado con la clave de parámetro de solicitud seleccionada.
En la consulta JSONata, use '$' para representar la clave cuyo valor está cambiando de formato.
El campo Vista previa del valor de prueba sirve para verificar los resultados de su consulta en tiempo real.
- Haga clic en Terminado.
- (Opcional) Si está agregando el parámetro de solicitud en el cuerpo de la solicitud de API:
- En el encabezado para Entorno a la izquierda, seleccione el entorno apropiado.
- Seleccione la pestaña Cuerpo.
- Agregue el objeto JSON usando el parámetro de solicitud como valor encerrado en llaves dobles.
Casos de uso comunes para cambiar el formato de valores
En el propio generador de integraciones, se pueden definir los parámetros de solicitud con solo asignarlos a claves específicas. Si bien es cierto que estos valores pueden funcionar tal cual, también existen situaciones en las que es necesario transformarlos o cambiarles el formato para que cumplan los requisitos del sistema externo.
Por ejemplo, podría desear:
- Cambiar el formato de las fechas. Cambie el formato de una fecha de MM/DD/AAAA a AAAA-MM-DD o al formato ISO 8601 para cumplir los requisitos de API.
- Realizar operaciones con cadenas. Manipule cadenas (con operaciones como agregar o quitar caracteres), combine varios campos o transforme cadenas para que contengan HTML.
- Aplicar lógica condicional. Aplique condiciones, como verificar si un campo está vacío o asignar un valor predeterminado si es necesario.
Esta sección contiene los siguientes ejemplos:
- Escenario: Cambiar el formato de las fechas
- Escenario: Cambiar el formato de los URL para poder hacer clic en los vínculos
- Escenario: Cambiar el formato de una transcripción de chat para que sea más legible
Escenario: Cambiar el formato de las fechas
En este escenario, un extremo necesita verificar una fecha con el formato AAAA-MM-DD o un formato ISO 8601. Sin embargo, para la conversación, prefiere que las fechas sigan el formato DD/MM/AAAA, que es más fácil para el usuario.
En este caso, la consulta JSONata que le conviene usar es esta:
$substring($, 6, 10) & "-" & $substring($, 3, 2) & "-" & $substring($, 0, 2)
Escenario: Cambiar el formato de los URL para poder hacer clic en los vínculos
En este escenario, el objetivo es convertir los URL en vínculos en los que se puede hacer clic con solo buscar un texto (una subcadena) que comience por http:// o bien por https:// seguido de un número de caracteres que no sean espacios en blanco. Luego hay que sustituir esa subcadena (usando la función $replace de JSONata) por una cadena que envuelva el URL concordante en una etiqueta HTML <a> para que se cree un vínculo en el que se puede hacer clic.
En este caso, la consulta JSONata que le conviene usar es esta:
(
$text := "Chat transcript unavailable. Here is a link:https://www.zendesk.com. Here is another link: https://www.w3schools.com.";
$replace($text, /(https?:\/\/[^\s]+)/, '<a href="$1">$1</a>'
)
Escenario: Cambiar el formato de una transcripción de chat para que sea más legible
En este escenario, se necesita agregar una transcripción de chat a un ticket. Sin embargo, en su estado predeterminado, la transcripción de chat no es fácil de leer:
- Transcripción de chat - 2024-10-12 (13:04:10) Agente IA: Bienvenido al agente IA del generador de integraciones. (13:04:10) Agente IA: Elija la integración que desea probar: (13:04:10) Visitante: prueba c.id: d501304d-da09-4485-a4c7-1c708ec0005d Todas las horas en UTC
Lo deseable es convertirla a un formato que el usuario pueda entender mejor con solo separar cada mensaje en una línea nueva. Puesto que cada mensaje comienza con un paréntesis de apertura ( ( ) , se puede usar JSONata para que cada vez que encuentre un ( lo sustituya por un salto de línea seguido del (.
Al final, la conversación con el formato cambiado tendría este aspecto:
- Transcripción de chat - 2024-10-12
(13:04:10) Agente IA: Bienvenido al agente IA del generador de integraciones
(13:04:10) Agente IA: Elija la integración que desea probar:
(13:04:10) Visitante: prueba c.id: d501304d-da09-4485-a4c7-1c708ec0005d Todas las horas en UTC
En este caso, la consulta JSONata que le conviene usar es esta:
$replace($, “(“, “\n(“)
Además, tendrá que agregar este parámetro a la sección de cuerpo en su entorno para que se envíe con la solicitud:
{
"chatTranscript": "{{chatTranscript}}"
}