# Exemples de configuration (REST)

## Exemple 1 : Configuration service web - METEO 

Cette section décrit les différentes étapes de configuration d'un service web REST météo afin de répondre automatiquement aux demandes des utilisateurs. Pour cela, vous pouvez utiliser le service openweathermap (<https://openweathermap.org/api>). **Il vous sera nécessaire de créer un compte pour disposer d'une clé.**

### Création et configuration d'un service web

1- Allez sur **Contenu > Web Services**.&#x20;

2- Cliquez sur **Ajouter** puis sélectionnez **Web Service REST**.

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2Ft05xvCTwhnsbOMnTjEGe%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2011.08.36.png?alt=media&#x26;token=e424b22d-3dbb-4350-b9a9-084aa34c8c2c" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FYSVsF9ITi0fq9Yn9C9fV%2Fimage.png?alt=media&#x26;token=75a0cf58-caab-48b5-8e54-1c26604cb66e" alt=""><figcaption></figcaption></figure>

3- Remplissez les champs suivants dans "configuration d'un webservice"

* Nom : "Meteo" &#x20;
* URL : "<http://api.openweathermap.org/data/2.5/weather>"&#x20;
* Methode HTTP : Get&#x20;
* Type de réponse : JSON&#x20;

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FWmetoSnbz26KrtpoJ99b%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2014.09.33.png?alt=media&#x26;token=3148c6c2-6afc-43ae-815a-1d998030ee49" alt=""><figcaption></figcaption></figure>

4. Remplissez les champs suivants dans "paramètres"

* APPID : Le paramètre est envoyé par WolrdWeatherOnline après la création d'un compte
* lang : fr&#x20;
* q : ${capture.ville meteo}

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FKWjUvxpXI7wGQ92D45gB%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2014.16.13.png?alt=media&#x26;token=42edcb52-b4fc-4c42-ab09-f8d201000883" alt=""><figcaption></figcaption></figure>

5. Cliquez sur "Ajouter" dans la catégorie "variables de résultat" et ajouter les deux variables suivantes:

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2F51kEjVQrqvJ4gd5lNQiv%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2014.19.45.png?alt=media&#x26;token=6c15381d-5792-48b2-ac42-44327f26c0c1" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
Attention : les noms des variables sont libres mais doivent être cohérents avec ce qui est indiqué dans les connaissances. les noms des variables doivent être des caractères alphanumériques ou des caractères de soulignement et commencer par une lettre. Ils sont également sensibles aux majuscules et minuscules.
{% endhint %}

6. Modifier le format du résultat json avec les valeurs suivants :&#x20;

```
function dyduParseJSON(json) {
 // returns a map return {
     "name" : json.name, 
     "description" : json.weather[0].description, 
     "temperature" : parseInt(json.main.temp / 10)
      } 
      }
```

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FnS2T6LEmFh6zK4uJ6BaV%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2014.22.20.png?alt=media&#x26;token=ddcbee2f-759e-4ca2-928d-9b839cd8a555" alt=""><figcaption></figcaption></figure>

7\. Tester la configuration de votre service web

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FrAW9I9UMZa2bXqABfPm4%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2017.04.28.png?alt=media&#x26;token=02782355-f8d5-4481-a86c-544ffee1b002" alt=""><figcaption></figcaption></figure>

avec la valeur de test "Paris" dans les paramètres :&#x20;

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FyjaqsiJfAczKR8ahphHt%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2017.05.49.png?alt=media&#x26;token=53d2a4d9-94af-4dc2-8d95-54e19f33bf18" alt=""><figcaption></figcaption></figure>

### Création de la connaissance associée

L'objectif est maintenant de créer des connaissances pour fournir des données au service web et les restituer aux utilisateurs.

#### Configurer la question&#x20;

**Phrase de l'utilisateur :** la phrase doit ressembler à une demande pour connaître le temps qu'il fait dans une ville donnée. Le point important dans cette phrase est de ne pas oublier la variable.Dans notre exemple, la variable est appelée **ville** et elle est de type **Alphanumérique**.

1. Créez une connaissance " Quelle est la météo à" puis cliquer sur " T "&#x20;

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FjppBbYULj7WettkHBmLH%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2014.25.23.png?alt=media&#x26;token=5ebba3ec-c414-4516-bf51-1061a8cf4f58" alt="" width="237"><figcaption></figcaption></figure>

2. Cherchez la variable " Ville"&#x20;

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FM34HBegOv3FWEPIDAKUU%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2014.25.51.png?alt=media&#x26;token=bc416ae5-8574-4125-a401-0e3a35b9913c" alt="" width="274"><figcaption></figcaption></figure>

3. Cliquez sur le groupe ville puis nommez "nom de la variable"villemeteo"
4. Cliquez sur **mettre à jour**

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2F8JR0HyUHEHmauX74Z2YU%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2014.28.52.png?alt=media&#x26;token=d88af2b4-6713-4bb9-9366-9e71a13cb430" alt="" width="327"><figcaption></figcaption></figure>

5. Cliquez sur **Créer** pour créer la connaissance.&#x20;

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2Fj03c8PaPiqd0Fzt7kB0e%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2014.30.06.png?alt=media&#x26;token=c86b8b22-3cd2-4c99-b624-bacd8cc41190" alt="" width="375"><figcaption></figcaption></figure>

#### Configurer la réponse

La réponse donnée à l'utilisateur affichera la température et la ville comprise par le système pour identifier d'éventuelles différences.

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FHweDSA4IUstpMQJ841UH%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2014.33.39.png?alt=media&#x26;token=4cc6937e-bf9a-4256-956a-c17d00f08859" alt="" width="353"><figcaption></figcaption></figure>

{% hint style="info" %}
Il est important de noter que :&#x20;

* les variables récupérées du service web sont structurées comme suit : ${callapi.WebServiceName.variableName};
* les variables récupérées de la boîte de dialogue sont structurées comme suit : ${capture.VariableName}.
  {% endhint %}

Pour plus de détail :&#x20;

{% embed url="<https://www.youtube.com/watch?v=O5V8kwSW4_U>" %}

## Exemple 2 : Utiliser le service web dans une condition

Les services web peuvent être utilisés dans la connaissance mais aussi dans les conditions. Utilisez le service météo pour savoir s'il fait chaud ou froid dans une ville. Dans notre exemple, on considère qu'il fait chaud à plus de 20 degrés et froid dans le cas contraire.

1- Créez une nouvelle connaissance pour répondre.

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2Flq0D2MNnOONKJ9BPo8Ol%2FCapture%20d%E2%80%99e%CC%81cran%202023-09-12%20a%CC%80%2018.39.52.png?alt=media&#x26;token=c6db569c-172a-46a5-a7f7-b40a22f0b72e" alt=""><figcaption></figcaption></figure>

2- Créez les deux réponses possibles avec une nouvelle condition que vous laisserez vide pour le moment:&#x20;

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FOLhPbWli2KtD0Gmb3qL7%2Fimage.png?alt=media&#x26;token=b92bfe54-ca48-4023-ab84-88e9e4915696" alt="" width="340"><figcaption></figcaption></figure>

Une fois que la partie connaissance est prête, vous devez créer une nouvelle condition qui sera utilisée dans le web service. Pour cela, dirigez vous vers la page **Contenu > Condititions de contexte** .

1 - Cliquez sur **Ajouter une condition** et créez la condition associée :&#x20;

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FrTf3fCt5lW59eQTNwdHQ%2Fimage.png?alt=media&#x26;token=dfa7f4aa-fe59-43dc-bbe4-fe6713b54990" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
A noter que l'opération est de type **expression mathématique** et la valeur doit être une expression correcte avec **x** la variable retournée par l'expression dans **Condition**. Ici, on doit vérifier que **callapi.TestWeather.Temperture > 20**.
{% endhint %}

Enfin, vous devez utilisez cette nouvelle condition dans la connaissance que nous avons créé. Pour ce faire:&#x20;

1- Modifiez la condition, sélectionnez **IsTempertureGreaterThan20**

**2-** Cliquez sur **Mettre à jour**.

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FwsFJTXfgsuLH2GKCgKo1%2Fimage.png?alt=media&#x26;token=372f4e11-d627-43aa-9c63-421612d36d00" alt="" width="344"><figcaption></figcaption></figure>

Vous pouvez maintenant tester la connaissance avec votre bot.

## Exemple 3 : Configuration service web - adresse IP

Nous allons ici utiliser les services web httpbin : <http://httpbin.org/> et plus précisément le service web IP permettant de retourner l'IP de l'utilisateur qui le demande.

### Création et configuration du service web

1- Créez un service web en mode REST.

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FIfagqILNC1dwgKWRvS9d%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2017.11.25.png?alt=media&#x26;token=f95d5304-cec9-4db5-a4b9-ac7bc0f89013" alt=""><figcaption></figcaption></figure>

2- Entrez le code JSON dans la section **Variables de résultat:**&#x20;

```
function dyduParseJSON(json) {
	 return {'ip' : json.origin};
}
```

3 - Entrez la variables "IP" en cliquant sur "ajouter". Vous pouvez ajouter autant de variables que vous le souhaitez.&#x20;

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2Frf1L4u1RHFEM5JtQ6bTy%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2017.13.50.png?alt=media&#x26;token=36a22fd2-111f-4395-b676-d7082b5d909a" alt=""><figcaption></figcaption></figure>

4- Cliquez ensuite sur **Sauvegarder**

**5-** Cliquez sur le bouton **Tester**  pour vérifier que le service web est opérationnel.

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FIWTLmWeI2QDZvY7ANKue%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2017.15.03.png?alt=media&#x26;token=bdbbc67a-489d-40f8-8a5e-7c901fd47dc8" alt="" width="262"><figcaption></figcaption></figure>

S'il n'y a pas d'erreur, l'IP vous sera retourné sinon il se peut qu'un élément ERROR fasse son apparition. Il est important de mentionner que les services web HTTPS peuvent ne pas fonctionner. Si tel est le cas, il vous suffit de retirer le « S » pour utiliser uniquement le protocole HTTP.

### Création de la connaissance associée

Dirigez-vous ensuite sur la page **Contenus > Connaissances** puis créez une nouvelle connaissance comme l'exemple ci-dessous :&#x20;

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FpzJdHIAllUcA4W9UyFnE%2Fimage.png?alt=media&#x26;token=c0121594-3118-479a-bf43-b3cc86f80d9f" alt="" width="274"><figcaption></figcaption></figure>

Vous pouvez ensuite tester votre connaissance en posant la question à votre bot par le biais de la boîte de dialogue de test. Posez lui la question « Quelle est mon IP ? » et le bot vous retournera votre adresse IP.

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2Fypov2jjmfKsh2UeqDtfN%2FCapture%20d%E2%80%99e%CC%81cran%202023-12-12%20a%CC%80%2017.17.45.png?alt=media&#x26;token=99e837c6-60ea-4d6e-87c8-1f5d60b45490" alt="" width="268"><figcaption></figcaption></figure>

## Exemple 4 : Envoi de pièce jointe multiple

Par exemple, si votre bot propose de créer un ticket au support IT, vous pouvez dans le parcours de création de ticket, proposer à l’utilisateur d’ajouter une ou plusieurs pièces jointes à son ticket.

Il existe deux façons différentes de configurer votre webservice pour l'envoi de pièces jointes multiples :

### Configuration par le corps (Body) de la requête (Format JSON)

Dans le corps (Body) de votre requête POST, utilisez la fonction `${DialogAllLastFilesUploaded()}`. Les trois paramètres que vous passez entre parenthèses définissent les noms des clés qui apparaîtront dans le JSON final.

* Paramètre 1 : Nom de la clé pour le nom du fichier.
* Paramètre 2 : Nom de la clé pour le type de contenu.
* Paramètre 3 : Nom de la clé pour le contenu en base64.

Exemple du corps de votre Web Service :

```
{
  "summary": "Nouveau ticket",
  "project": {
    "id": "81-276"
  },
  "files": ${DialogAllLastFilesUploaded("fileName", "fileContentType", "base64Data")}
}
```

Au moment de l'exécution, le moteur remplace la variable par un tableau d'objets. Voici à quoi ressemble le flux JSON envoyé à votre serveur si l'utilisateur a téléchargé deux fichiers :

```
{
  "summary": "Nouveau ticket",
  "project": {
    "id": "81-276"
  },
  "files": [
    {
      "fileName": "Fichier1.txt",
      "fileContentType": "text/plain; charset=UTF-8",
      "base64Data": "VGVzdAo="
    },
    {
      "fileName": "Fichier2.txt",
      "fileContentType": "text/plain; charset=UTF-8",
      "base64Data": "VGVzdDIK"
    }
  ]
}
```

### Configuration en passant par un paramètre (Format Multipart)

Cette seconde approche est idéale si le serveur de destination attend une requête au format standard d'envoi de fichiers (`multipart/form-data`) plutôt qu'un flux JSON. Elle offre l'avantage d'être générée automatiquement par le système.

Comment configurer cette méthode ? Au lieu de construire manuellement le corps (Body) de votre requête, il vous suffit d'utiliser la fonction directement dans les paramètres de votre Web Service.

* La fonction à utiliser : Renseignez simplement `${DialogAllLastFilesUploaded()}`.
* Point d'attention : Contrairement à la méthode par le Body, les parenthèses doivent impérativement rester vides. Il n'est pas nécessaire de définir des noms de clés.

Que se passe-t-il lors de l'exécution ? L'outil prend le relais et formate la requête pour vous. Il génère automatiquement un corps de type `multipart/form-data`, qui est le standard du web pour transférer des pièces jointes.

Pour structurer cet envoi, le système crée de lui-même un identifiant de séparation unique (appelé *boundary*) qui permet au serveur de destination de distinguer clairement chaque fichier envoyé.

L'en-tête (Header) de la requête générée ressemblera alors à ceci :

```
Content-Type: multipart/form-data; boundary=fpzDzOf56Xecd3EcRuwZwVNnC8S5Ln0k
```

***

Les pièces jointes envoyées par les utilisateurs sont accessibles depuis la conversation concernée via un lien sécurisé par un token.

En cas de purge, d’anonymisation ou chiffrement des conversations, les pièces jointes transmises sont prises en compte : elles ne seront donc plus accessibles selon les critères de purge, anonymisation ou chiffrement définis.

## Exemple 5 : Envoi de pièce jointe simple

L'envoie de pièce jointe à un service web suppose qu'une pièce jointe ait été  chargée par l'utilisateur au cours de la conversation.

Si plusieurs pièces jointes sont chargées au cours de la même conversation, c'est la pièce jointe chargée lors de l'interaction la plus récente qui sera prise en compte pour être envoyée au service web (il est ainsi possible de modifier la pièce jointe à charger en cas d'erreur de selection depuis la chatbox).

Les données de la pièce jointe à envoyer sont accessibles par l'utilisation des trois clés suivants:

* ${DialogLastFileUploadedContent()}
* ${DialogLastFileUploadedContentType()}
* ${DialogLastFileUploadedName()}

{% hint style="warning" %}
Avant la version edge\_2025-12-09, le système utilisait ces variables

Ces variables sont toujours fonctionnelles mais ne récupèrent que le premier fichier envoyé et ne sont plus mises à jour. Il est recommandé d'utiliser la nouvelle fonction pour gérer les envois multiples.
{% endhint %}

Le premier mot clé fait référence au contenu du fichier, le second à son type et le troisième à son nom.

Dans la zone "Corps", ces trois clés peuvent être utilisées pour faire parti d'un contenu au format JSON, la valeur de DialogLastFileUploadedContent sera encodée au format Base64.

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FoSRu3sTrE3fKLHbTrKGx%2Fimage.png?alt=media&#x26;token=cb40d7b1-b456-41b6-b8a6-1e77d587c483" alt=""><figcaption></figcaption></figure>

Dans la zone "Paramètres", seule la clé ${DialogLastFileUploadedContent()} est nécessaire.&#x20;

Lorsqu'elle est présente, le fichier correspondant sera envoyé au service web sous forme de multipart-form-data, avec les meta data associées (nom du fichier et type de contenu).

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2Firp33T6FI3V5Q0F0MVP6%2Fimage.png?alt=media&#x26;token=9ad65446-abd4-478e-874f-593ac0554f8e" alt=""><figcaption></figcaption></figure>

Si la zone "Corps" est utilisée pour envoyer un fichier à un service web, cela n'a pas de sens d'utiliser aussi la zone "Paramètres" à cette fin, et vice-versa.