Dans le créateur d’intégration, les paramètres de demande vous permettent d’extraire les données (paramètres conversationnels) des conversations de l’agent IA et de les transférer à des points de terminaison externes. Dans certains cas, il est possible que vous deviez transformer ou reformater ces données avant de les envoyer dans une demande API sous la forme d’une requête URL ou dans le corps de la demande. Pour ce faire, vous pouvez utiliser JSONata, un langage de requête et de transformation puissant.
Cet article aborde les sujets suivants :
- Reformatage de la valeur d’un paramètre de demande
- Exemples de cas d’utilisation courants pour le reformatage des valeurs
Articles connexes :
Reformatage de la valeur d’un paramètre de demande
Vous pouvez reformater la valeur d’un paramètre de demande en utilisant JSONata.
Pour reformater la valeur d’un paramètre de demande
- Dans l’espace de travail des agents IA, en haut à droite, utilisez le champ déroulant des agents IA pour sélectionner votre agent IA.
- Dans le menu principal sur la gauche, cliquez sur Intégrations API.
- Sélectionnez ou créez une intégration.
- Sur la page Paramètres de la demande, sélectionnez ou créez le paramètre de demande pour lequel vous voulez reformater la valeur.
- Dans le champ Valeur test, sélectionnez l’icône de reformatage de valeur (
).
- Dans la boîte de dialogue Reformatage de valeur, dans le champ Reformatage de JSONata, utilisez JSONata pour transformer ou reformater la valeur associée à la clé du paramètre de demande sélectionnée.
Dans votre requête JSONata, utilisez '$' pour représenter la clé pour laquelle vous reformatez la valeur.
Le champ Aperçu de la valeur de test vous permet de vérifier les résultats de votre requête en temps réel.
- Cliquez sur Terminé.
- (facultatif) Si vous ajoutez le paramètre de demande au corps d’une demande API :
- Sous Environnement sur la gauche, sélectionnez l’environnement approprié
- Sélectionnez l’onglet Corps.
- Ajoutez votre objet JSON en utilisant le paramètre de demande comme valeur entre doubles accolades.
Cas d’utilisation courants pour le reformatage des valeurs
Dans le créateur d’intégration, vous pouvez définir des paramètres de demande en les affectant à des clés spécifiques. Ces valeurs fonctionnent parfois telles quelles, mais dans certains ces, vous devez les transformer ou les reformater pour qu’elles répondent aux exigences du système externe.
Vous pouvez par exemple vouloir :
- Reformater les dates : modifiez le format MM/JJ/AAAA d’une date et remplacez-le par le format AAAA-MM-JJ ou ISO 8601 pour satisfaire aux exigences de l’API.
- Effectuer des opérations sur les chaînes : manipulez les chaînes en ajoutant ou en supprimant des caractères, en combinant plusieurs champs ou en transformant les chaînes pour qu’elles contiennent du code HTML, par exemple
- Appliquer la logique conditionnelle : appliquez des conditions, comme vérifier qu’un champ est vide ou affecter une valeur par défaut, si besoin est.
Cette section contient les exemples suivants :
- Scenario : reformatage des dates
- Scenario : reformatage des URL pour que les liens soient cliquables
- Scenario : reformatage de la transcription d’un chat pour qu’elle soit plus facile à lire
Scénario : reformatage des dates
Dans ce scénario, votre point de terminaison doit vérifier une date au format AAAA-MM-JJ ou ISO 8601, mais vous voulez que vos dates s’affichent dans vos conversations dans un format plus convivial, soit JJ/MM/AAAA.
Voici la requête JSONata que vous utiliseriez dans ce scénario :
$substring($, 6, 10) & "-" & $substring($, 3, 2) & "-" & $substring($, 0, 2)
Scénario : reformatage des URL pour que les liens soient cliquables
Dans ce scénario, vous voulez convertir les URL en recherchant le texte (une sous-chaîne) qui commence par http:// ou https:// suivi par des caractères sans espacement. Vous devez alors utiliser la fonction JSONata $replace pour remplacer cette sous-chaîne par une chaîne qui entoure l’URL correspondante de marqueurs HTML <a> et crée ainsi un lien cliquable.
Voici la requête JSONata que vous utiliseriez dans ce scénario :
(
$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>'
)
Scénario : reformatage de la transcription d’un chat pour qu’elle soit plus facile à lire
Dans ce scénario, vous voulez ajouter la transcription d’un chat à un ticket. Cependant, dans sa forme par défaut, cette transcription est difficile à lire :
- Transcription du chat - 2024-10-12 (13:04:10) Agent IA : Bienvenue dans l’agent IA du créateur d’intégration ! (13:04:10) Agent IA : Choisissez l’intégration à tester : (13:04:10) Visiteur : teste c.id: d501304d-da09-4485-a4c7-1c708ec0005d Toutes les heures en UTC
Vous voulez transformer cette transcription et convertir dans un format plus convivial en séparant les messages sur des lignes différentes. Comme chaque nouveau message commence par une parenthèse ouvrante ( ( ) , vous pouvez utiliser JSONata pour remplacer chaque occurrence de ( par un saut de ligne suivi de (.
Voici à quoi ressemblerait la conversation reformatée :
- Transcription du chat - 2024-10-12
(13:04:10) Agent IA : Bienvenue dans l’agent IA du créateur d’intégration !
(13:04:10) Agent IA : Choisissez l’intégration à tester :
(13:04:10) Visiteur : teste c.id: d501304d-da09-4485-a4c7-1c708ec0005d Toutes les heures en UTC
Voici la requête JSONata que vous utiliseriez dans ce scénario :
$replace($, “(“, “\n(“)
En outre, vous devrez ajouter ce paramètre à la section Corps dans votre environnement pour qu’il soit envoyé avec votre demande.
{
"chatTranscript": "{{chatTranscript}}"
}