> For the complete documentation index, see [llms.txt](https://docs.dydu.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dydu.ai/developpeurs/reference-api/boite-de-dialogue-api.md).

# Boîte de dialogue API

Le moteur de dialogues peut être interrogé de deux façons :

* **en mode synchrone, avec l'API REST** : le bot répond uniquement quand l'utilisateur lui envoie une question. Dans le diagramme ci-dessous, les requêtes *talk* sont synchrones et leur résultat contient la réponse du bot ;
* **en mode asynchrone, avec une WebSocket** : le serveur peut envoyer des messages sans avoir été sollicité, par exemple lorsqu'un opérateur humain écrit à l'utilisateur.

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2Froijh3jZSEGznIwJgYIQ%2Fimage.png?alt=media&amp;token=13447808-d84d-4f7c-ab43-d8806e37e567" alt="" width="361"><figcaption></figcaption></figure>

## API REST (mode synchrone)

Vous pouvez tester ces API dans l'interface Swagger : dirigez-vous sur la page **Préférences > Api > Accès aux APIs**, cliquez sur le lien proposé puis sur **Chat**.

### Fonctionnement général

* **Adresse** : `https://<serveur>/servlet/api/chat/...`, en remplaçant `<serveur>` par l'adresse de votre plateforme.
* **Méthode** : `POST`, avec des paramètres de formulaire (`Content-Type: application/x-www-form-urlencoded`). Seules les API de lecture des variables et du statut utilisent `GET`.
* **Identifiant du bot** : il est toujours placé dans l'adresse (`/chat/talk/{botUUID}`). Vous le trouverez sur la page **Préférences > Api > Accès aux APIs**.
* **Authentification** : aucune par défaut. Si un filtre OIDC est défini sur votre bot, ajoutez l'en-tête `Authorization: Bearer <jeton JWT>`.
* **Réponses** : les valeurs des réponses JSON sont encodées en base64. Par exemple, `"typeResponse":"RE1VbmRlcnN0b29kUXVlc3Rpb24="` correspond à « DMUnderstoodQuestion ». Certaines API renvoient du JavaScript (par exemple `console.log('...')`).

{% hint style="warning" %}
Le nom du paramètre d'identifiant de conversation dépend de l'API : `contextUuid` pour la plupart des API, mais `contextUUID` pour les API de satisfaction (`feedback`) et `contextId` pour `reading`. Les noms de paramètres sont sensibles à la casse.
{% endhint %}

### Enchaînement type d'une conversation

1. Récupérez un identifiant de conversation avec [Récupérer un identifiant de conversation](#recuperer-un-identifiant-de-conversation), ou envoyez directement une première question avec [Envoyer une question](#envoyer-une-question).
2. Envoyez les questions suivantes en indiquant cet identifiant.
3. Envoyez l'avis de l'utilisateur avec les API de [satisfaction](#satisfaction).

L'identifiant de conversation regroupe toutes les interactions d'une même conversation. Lorsqu'il n'est pas utilisé pendant 10 minutes, la conversation est archivée et l'identifiant n'est plus valable. Si vous envoyez un identifiant invalide ou expiré, le serveur en crée un nouveau.

### Paramètres communs

Ces paramètres sont utilisés par plusieurs API. Le tableau de chaque API indique ceux qu'elle accepte.

<table><thead><tr><th width="250">Paramètre</th><th>Description</th></tr></thead><tbody><tr><td><code>userInput</code></td><td>Question de l'utilisateur. Seuls les 600 premiers caractères sont pris en compte.</td></tr><tr><td><code>space</code></td><td>Espace de consultation. Pour n'utiliser aucun espace en particulier, indiquez « Defaut ».</td></tr><tr><td><code>language</code></td><td>Langue de la conversation, en anglais et avec une majuscule : « French », « English », « Dutch », « Spanish », « German »… Si l'utilisateur écrit dans une autre langue gérée par le bot, le bot répond dans la langue utilisée.</td></tr><tr><td><code>alreadyCame</code></td><td><code>true</code> si l'utilisateur est déjà venu, <code>false</code> sinon.</td></tr><tr><td><code>clientId</code></td><td>Identifiant de l'utilisateur. Sans ce paramètre, la conversation est anonyme. Dans la page de lecture des conversations du BMS, il n'est affiché qu'aux administrateurs.</td></tr><tr><td><code>userUrl</code></td><td>URL de la page depuis laquelle la question a été posée.</td></tr><tr><td><code>browser</code></td><td>Navigateur de l'utilisateur.</td></tr><tr><td><code>os</code></td><td>Système d'exploitation de l'utilisateur.</td></tr><tr><td><code>contextType</code></td><td>Type de conversation : « Web », « Vocal », « Android » ou « iOS ».</td></tr><tr><td><code>qualificationMode</code></td><td><code>true</code> : mode qualification (recette). Les connaissances publiées et validées sont utilisables et les conversations ne sont pas comptabilisées dans les statistiques. <code>false</code> (par défaut) : seules les connaissances publiées sont utilisables et les conversations sont comptabilisées.</td></tr><tr><td><code>solutionUsed</code></td><td>Solution utilisée, en majuscules : « ASSISTANT », « LIVECHAT », « ASSISTANT_AND_LIVECHAT », « FIELDBOX », « VOCAL », « TEAMS », « WHATSAPP », « MESSENGER », « INSTAGRAM », « SMSMODE »…</td></tr><tr><td><code>pureLiveChat</code></td><td><code>true</code> pour activer l'option pureLiveChat.</td></tr><tr><td><code>extraParameters</code></td><td>Type de la question, au format JSON : <code>{"type":"reword_auto"}</code>. Sans ce paramètre, la question est considérée comme saisie par l'utilisateur. Ce type n'influence pas la réponse : il sert aux statistiques. Voir les <a href="#types-de-question-extraparameters">valeurs possibles</a>.</td></tr><tr><td><code>variables</code></td><td>Variables de contexte à transmettre au bot, au format JSON. Exemple : <code>{"name":"dupont","InvoiceSum":"123.45"}</code>. Ces variables peuvent ensuite être utilisées dans le BMS pour personnaliser les réponses.</td></tr><tr><td><code>doNotRegisterInteraction</code></td><td><code>true</code> : l'interaction n'est pas enregistrée. <code>false</code> : elle est enregistrée.</td></tr><tr><td><code>competency</code></td><td>Compétence livechat à utiliser.</td></tr><tr><td><code>timestamp</code></td><td>Valeur numérique (nombre entier).</td></tr><tr><td><code>templateFormats</code></td><td>Formats de modèles de réponse acceptés, séparés par des points-virgules.</td></tr></tbody></table>

#### **Types de question (extraParameters)**

<table data-header-hidden><thead><tr><th width="250"></th><th></th></tr></thead><tbody><tr><td>Valeur de <code>type</code></td><td>Description</td></tr><tr><td><code>reword_auto</code></td><td>Clic sur une reformulation proposée par le bot lorsqu'il n'a pas compris la question.</td></tr><tr><td><code>redirection</code></td><td>Clic sur une URL de la réponse du bot, ouverte dans la même page.</td></tr><tr><td><code>redirection_newpage</code></td><td>Clic sur une URL de la réponse du bot, ouverte dans un nouvel onglet.</td></tr><tr><td><code>redirection_invalidlink</code></td><td>Clic sur un lien invalide de la réponse du bot.</td></tr><tr><td><code>javascript</code></td><td>Clic sur un lien de la réponse du bot qui exécute du JavaScript (par exemple une escalade vers le livechat).</td></tr><tr><td><code>redirection_knowledge</code></td><td>Clic sur un lien de la réponse du bot qui affiche la réponse d'une autre connaissance.</td></tr><tr><td><code>redirection_consultation_space</code></td><td>Clic sur un lien proposé par le bot pour obtenir la réponse dans un autre espace de consultation.</td></tr><tr><td><code>redirection_personality</code></td><td>Clic sur un lien de redirection vers une personnalité.</td></tr><tr><td><code>before_close_dialog</code></td><td>Question envoyée avant la fermeture de la conversation.</td></tr><tr><td><code>reword_teaser</code></td><td>Clic sur une reformulation du teaser.</td></tr><tr><td><code>exportable_faq</code></td><td>Question issue de la FAQ exportable.</td></tr><tr><td><code>reword_feedback</code></td><td>Clic sur une reformulation proposée après un avis de satisfaction.</td></tr><tr><td><code>dtmf</code></td><td>Touche saisie sur le clavier du téléphone (bot vocal).</td></tr></tbody></table>

### Démarrer et mener une conversation

#### **Récupérer un identifiant de conversation**

`POST /chat/context/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>space</code></td><td>Oui</td><td>Espace de consultation.</td></tr><tr><td><code>language</code></td><td>Oui</td><td>Langue de la conversation.</td></tr><tr><td><code>alreadyCame</code>, <code>clientId</code>, <code>os</code>, <code>browser</code>, <code>contextType</code>, <code>qualificationMode</code>, <code>solutionUsed</code>, <code>pureLiveChat</code></td><td>Non</td><td>Voir <a href="#parametres-communs">Paramètres communs</a>.</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/context/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "space=Defaut&language=French&alreadyCame=true&clientId=jmanier&contextType=Web&solutionUsed=ASSISTANT"
```

Réponse :

```
console.log('46064f7a-d026-4bf3-ab5d-69a9303a81e7');
```

#### **Envoyer une question**

Deux API sont disponibles :

* `POST /chat/talk/{botUUID}` : pour la première question, sans identifiant de conversation. Le serveur crée une nouvelle conversation ;
* `POST /chat/talk/{botUUID}/{contextUUID}` : pour les questions suivantes, avec l'identifiant de conversation dans l'adresse.

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>userInput</code></td><td>Oui</td><td>Question de l'utilisateur.</td></tr><tr><td><code>space</code></td><td>Oui</td><td>Espace de consultation.</td></tr><tr><td><code>language</code></td><td>Oui</td><td>Langue de la conversation.</td></tr><tr><td><code>userUrl</code>, <code>alreadyCame</code>, <code>clientId</code>, <code>os</code>, <code>browser</code>, <code>contextType</code>, <code>qualificationMode</code>, <code>solutionUsed</code>, <code>pureLiveChat</code>, <code>extraParameters</code>, <code>variables</code>, <code>doNotRegisterInteraction</code>, <code>competency</code>, <code>timestamp</code>, <code>templateFormats</code></td><td>Non</td><td>Voir <a href="#parametres-communs">Paramètres communs</a>.</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/talk/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20/e6a5ae08-703c-4ddd-9d57-fa07a8908f0d" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d 'userInput=Bonjour&space=Defaut&language=French&solutionUsed=ASSISTANT&variables={"name":"dupont"}'
```

Réponse (les valeurs sont encodées en base64) :

```
{"values":{"knowledgeId":168168,"typeResponse":"RE1VbmRlcnN0b29kUXVlc3Rpb24=","contextId":"ZTZhNWFlMDgtNzAzYy00ZGRkLTlkNTctZmEwN2E4OTA4ZjBk","serverTime":1542039200149,"language":"ZnI=","botId":"ZWYwN2EzN2EtMmYzOC00NGYxLWEyYzQtZDJlNzFlN2M2ZDIw","text":"Qm9uam91ciAh","hasProfilePicture":false,"startLivechat":false,"keepPopinMinimized":false,"human":false,"askFeedback":true},"type":"talkResponse"}
```

#### **Enregistrer la visite d'un utilisateur**

`POST /chat/welcomecall/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>contextUuid</code></td><td>Oui</td><td>Identifiant de la conversation.</td></tr><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>language</code></td><td>Oui</td><td>Langue de la conversation.</td></tr><tr><td><code>space</code></td><td>Oui</td><td>Espace de consultation.</td></tr><tr><td><code>qualificationMode</code></td><td>Non</td><td>Mode qualification.</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/welcomecall/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "contextUuid=e6a5ae08-703c-4ddd-9d57-fa07a8908f0d&solutionUsed=ASSISTANT&language=French&space=Defaut"
```

Réponse :

```
/*logged*/
```

#### **Indiquer que l'utilisateur est en train d'écrire**

`POST /chat/typing/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>contextUuid</code></td><td>Oui</td><td>Identifiant de la conversation.</td></tr><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>content</code></td><td>Oui</td><td>Texte en cours de saisie.</td></tr><tr><td><code>typing</code></td><td>Non</td><td><code>true</code> si l'utilisateur est en train d'écrire.</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/typing/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "contextUuid=e6a5ae08-703c-4ddd-9d57-fa07a8908f0d&solutionUsed=ASSISTANT&content=Bonj&typing=true"
```

Réponse :

```
{}
```

#### **Vérifier s'il y a une nouvelle réponse (livechat)**

En mode livechat par interrogation régulière (polling), vérifie si une nouvelle réponse attend l'utilisateur.

`POST /chat/poll/last/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>contextUuid</code></td><td>Oui</td><td>Identifiant de la conversation.</td></tr><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>language</code></td><td>Oui</td><td>Langue de la conversation.</td></tr><tr><td><code>space</code></td><td>Oui</td><td>Espace de consultation.</td></tr><tr><td><code>lastPoll</code></td><td>Oui</td><td>Valeur numérique de la dernière interrogation.</td></tr><tr><td><code>format</code></td><td>Non</td><td>Format de la réponse : « JSon » (par défaut), « XML », « JSonDydu », « Vocal » ou « Html ».</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/poll/last/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "contextUuid=e6a5ae08-703c-4ddd-9d57-fa07a8908f0d&solutionUsed=ASSISTANT&language=French&space=Defaut&lastPoll=12"
```

Réponse :

```
dydu_notification('{"code":"RGlhbG9nRmluaXNoZWQ=","context":null,"serverTime":1542034663648,"text":"TGEgY29udmVyc2F0aW9uIGVzdCB0ZXJtaW7DqWU="}');
DYDUServlet.closeDialog(true, false);
```

### Historique

#### **Récupérer l'historique d'une conversation**

`POST /chat/history/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="99">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>contextUuid</code></td><td>Oui</td><td>Identifiant de la conversation en cours.</td></tr><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>dialog</code></td><td>Non</td><td>Identifiant d'une autre conversation dont vous voulez l'historique.</td></tr><tr><td><code>uiLocale</code></td><td>Non</td><td>Langue de l'interface.</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/history/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "contextUuid=e6a5ae08-703c-4ddd-9d57-fa07a8908f0d&solutionUsed=ASSISTANT"
```

Réponse :

```
dydu_showDialogHistory();
```

#### **Récupérer les conversations précédentes d'un utilisateur**

`POST /chat/dialog/previous/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>clientId</code></td><td>Oui</td><td>Identifiant de l'utilisateur.</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/dialog/previous/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "solutionUsed=ASSISTANT&clientId=jmanier"
```

Réponse :

```
{"values":{"previousDialogs":[]},"type":"getPreviousDialogsResponse"}
```

### Satisfaction

#### **Envoyer un avis de satisfaction**

`POST /chat/feedback/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>contextUUID</code></td><td>Oui</td><td>Identifiant de la conversation.</td></tr><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>feedBack</code></td><td>Oui</td><td>« positive », « negative » ou « withoutAnswer ».</td></tr><tr><td><code>interactionDate</code></td><td>Non</td><td>Date de l'interaction concernée (valeur numérique).</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/feedback/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "contextUUID=e6a5ae08-703c-4ddd-9d57-fa07a8908f0d&solutionUsed=ASSISTANT&feedBack=positive"
```

#### **Envoyer un commentaire de satisfaction**

`POST /chat/feedback/comment/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>contextUUID</code></td><td>Oui</td><td>Identifiant de la conversation.</td></tr><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>comment</code></td><td>Oui</td><td>Commentaire de l'utilisateur.</td></tr><tr><td><code>interactionDate</code></td><td>Non</td><td>Date de l'interaction concernée (valeur numérique).</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/feedback/comment/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "contextUUID=e6a5ae08-703c-4ddd-9d57-fa07a8908f0d&solutionUsed=ASSISTANT&comment=Merci"
```

#### **Envoyer la raison d'une insatisfaction**

`POST /chat/feedback/insatisfaction/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>contextUUID</code></td><td>Oui</td><td>Identifiant de la conversation.</td></tr><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>choiceKey</code></td><td>Oui</td><td>Clé de la raison d'insatisfaction choisie.</td></tr><tr><td><code>interactionDate</code></td><td>Non</td><td>Date de l'interaction concernée (valeur numérique).</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/feedback/insatisfaction/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "contextUUID=e6a5ae08-703c-4ddd-9d57-fa07a8908f0d&solutionUsed=ASSISTANT&choiceKey=choiceKey_value"
```

### Variables de contexte

#### **Ajouter ou supprimer une variable**

`POST /chat/variable/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>contextUuid</code></td><td>Oui</td><td>Identifiant de la conversation.</td></tr><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>name</code></td><td>Oui</td><td>Nom de la variable.</td></tr><tr><td><code>value</code></td><td>Non</td><td>Valeur de la variable.</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/variable/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "contextUuid=e6a5ae08-703c-4ddd-9d57-fa07a8908f0d&solutionUsed=ASSISTANT&name=test&value=1"
```

#### **Ajouter ou supprimer plusieurs variables**

`POST /chat/variables/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>contextUuid</code></td><td>Oui</td><td>Identifiant de la conversation.</td></tr><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>variables</code></td><td>Oui</td><td>Variables au format JSON. Exemple : <code>{"name":"dupont","InvoiceSum":"123.45"}</code>.</td></tr></tbody></table>

#### **Lire les variables d'une conversation**

`GET /chat/variables/{botUUID}/{contextUuid}`

Renvoie les variables de contexte de la conversation au format JSON.

### Questionnaires

#### **Récupérer la configuration d'un questionnaire**

`POST /chat/survey/configuration/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>contextUuid</code></td><td>Oui</td><td>Identifiant de la conversation.</td></tr><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>language</code></td><td>Oui</td><td>Langue de la conversation.</td></tr><tr><td><code>surveyId</code></td><td>Oui</td><td>Identifiant du questionnaire.</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/survey/configuration/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "contextUuid=e6a5ae08-703c-4ddd-9d57-fa07a8908f0d&solutionUsed=ASSISTANT&language=French&surveyId=20f4ab33-eb28-47d7-850c-60e5c6a352b3"
```

Réponse :

```
{"values":{"surveyId":"MjBmNGFiMzMtZWIyOC00N2Q3LTg1MGMtNjBlNWM2YTM1MmIz","name":"TmV3IHN1cnZleQ==","contextId":"ZTZhNWFlMDgtNzAzYy00ZGRkLTlkNTctZmEwN2E4OTA4ZjBk"},"type":"surveyConfigurationResponse"}
```

#### **Envoyer les réponses à un questionnaire**

`POST /chat/survey/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>contextUuid</code></td><td>Oui</td><td>Identifiant de la conversation.</td></tr><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>fields</code></td><td>Oui</td><td>Réponses aux champs du questionnaire.</td></tr><tr><td><code>interactionSurveyAnswer</code></td><td>Non</td><td><code>true</code> si le questionnaire porte sur une interaction.</td></tr></tbody></table>

### Rechercher dans les connaissances

#### **Rechercher une connaissance**

`POST /chat/search/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>language</code></td><td>Oui</td><td>Langue de recherche. Sans ce paramètre, l'API renvoie une erreur 400 « Missing language ».</td></tr><tr><td><code>search</code></td><td>Non</td><td>Texte recherché.</td></tr><tr><td><code>space</code></td><td>Non</td><td>Espace de consultation.</td></tr><tr><td><code>searchInParents</code></td><td>Non</td><td><code>true</code> (par défaut) pour chercher aussi dans les bots parents.</td></tr><tr><td><code>searchInPersonalities</code></td><td>Non</td><td><code>true</code> pour chercher aussi dans les personnalités. Vaut <code>false</code> si le paramètre n'est pas envoyé.</td></tr><tr><td><code>onlyShowRewordables</code></td><td>Non</td><td><code>true</code> (par défaut) pour ne renvoyer que les connaissances pouvant être proposées en reformulation.</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/search/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "language=French&search=horaires"
```

#### **Récupérer les connaissances les plus consultées**

`POST /chat/topknowledge/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>language</code></td><td>Oui</td><td>Langue de la conversation.</td></tr><tr><td><code>period</code></td><td>Oui</td><td>Période : « Today », « Yesterday », « Last7Days » ou « Last30Days ». Une valeur non reconnue est remplacée par « Last30Days ».</td></tr><tr><td><code>space</code></td><td>Non</td><td>Espace de consultation.</td></tr><tr><td><code>tag</code></td><td>Non</td><td>Nom ou identifiant (tagID) d'une thématique. Pour trouver le tagID, faites un clic droit sur la thématique puis <strong>Inspecter</strong> : dans <code>div id="tag-6671"</code>, le tagID est « 6671 ».</td></tr><tr><td><code>includeTagChildren</code></td><td>Non</td><td><code>true</code> pour inclure les sous-thématiques.</td></tr><tr><td><code>qualificationMode</code></td><td>Non</td><td>Mode qualification.</td></tr><tr><td><code>maxKnowledge</code></td><td>Non</td><td>Nombre maximum de connaissances renvoyées (10 par défaut).</td></tr><tr><td><code>withContent</code></td><td>Non</td><td><code>true</code> pour renvoyer aussi le contenu des connaissances.</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/topknowledge/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "solutionUsed=ASSISTANT&language=French&period=Last7Days&maxKnowledge=5"
```

Réponse (la liste des connaissances `knowledgeArticles` est encodée en base64) :

```
{"values":{"knowledgeArticles":"W3sicmV3b3JkIjoi...","serverTime":1542040024994,"tagName":"VGFnX3ZhbHVl"},"type":"topKnowledgeResponse"}
```

### Autres API

#### **Envoyer une erreur**

`POST /chat/error/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>contextUuid</code></td><td>Oui</td><td>Identifiant de la conversation.</td></tr><tr><td><code>solutionUsed</code></td><td>Oui</td><td>Solution utilisée.</td></tr><tr><td><code>error</code></td><td>Oui</td><td>Type d'erreur.</td></tr><tr><td><code>message</code></td><td>Oui</td><td>Message d'erreur.</td></tr><tr><td><code>browser</code>, <code>os</code>, <code>stackTrace</code>, <code>jsCreation</code>, <code>userUrl</code></td><td>Non</td><td>Informations complémentaires sur l'erreur.</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/error/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "contextUuid=e6a5ae08-703c-4ddd-9d57-fa07a8908f0d&solutionUsed=ASSISTANT&error=js%20error&message=test%20error"
```

Réponse :

```
{}
```

#### **Enregistrer une demande RGPD**

`POST /chat/gdpr/{botUUID}`

<table><thead><tr><th width="250">Paramètre</th><th width="100">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>clientId</code></td><td>Oui</td><td>Identifiant de l'utilisateur.</td></tr><tr><td><code>object</code></td><td>Oui</td><td>« Get » pour obtenir ses données, « Delete » pour les supprimer.</td></tr><tr><td><code>mail</code></td><td>Oui</td><td>Adresse mail de l'utilisateur.</td></tr><tr><td><code>language</code></td><td>Non</td><td>Langue du mail envoyé.</td></tr></tbody></table>

Requête curl :

```
curl -X POST "https://<serveur>/servlet/api/chat/gdpr/ef07a37a-2f38-44f1-a2c4-d2e71e7c6d20" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
  -d "clientId=jmanier&object=Get&mail=jmanier%40dydu.ai&language=French"
```

Réponse :

```
{}
```

#### **API complémentaires**

Ces API sont aussi disponibles dans la catégorie **Chat** de l'interface Swagger :

<table><thead><tr><th width="375">API</th><th>Description</th></tr></thead><tbody><tr><td><code>GET /chat/status/{botUUID}/{contextId}</code></td><td>Obtenir le statut d'une conversation.</td></tr><tr><td><code>POST /chat/availablecontext/{botUUID}/{contextUuid}</code></td><td>Vérifier si un identifiant de conversation est toujours valable.</td></tr><tr><td><code>POST /chat/reading/{botUUID}/</code></td><td>Indiquer si l'utilisateur lit la conversation (paramètres <code>contextId</code>, <code>solutionUsed</code>, <code>reading</code>).</td></tr><tr><td><code>POST /chat/registerlastinteraction/{botUUID}</code></td><td>Indiquer si la dernière interaction doit être enregistrée (paramètres <code>contextUUID</code>, <code>registerLastInteraction</code>).</td></tr><tr><td><code>POST /chat/pushrules/{botUUID}</code></td><td>Récupérer les règles de ciblage comportemental.</td></tr><tr><td><code>GET /chat/attachment/download/{botId}/{contextUUID}/{attachmentUUID}</code></td><td>Télécharger une pièce jointe de la conversation (paramètre <code>token</code> obligatoire).</td></tr></tbody></table>

## WebSocket (mode asynchrone)

Le mode asynchrone utilise une WebSocket, avec le sous-protocole **dyduchat**. Le point d'accès est `/chatWs`.

Ce mode est surtout utile lorsque l'utilisateur discute avec un opérateur humain : l'opérateur n'a pas besoin d'attendre une question de l'utilisateur pour répondre. Il peut écrire en premier ou envoyer plusieurs messages à la suite.

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2Ft3g7oZUxWnAL8VcXmGhv%2Fimage.png?alt=media&amp;token=e66b8111-46db-4a5d-a36c-e8fa9391d0ca" alt="" width="361"><figcaption></figcaption></figure>

### Requêtes du client

Le client envoie ses requêtes au format JSON. Toutes les valeurs des champs doivent être encodées en base64.

#### **Requête talk**

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FnxbQESwGrXSVcvsKSMVa%2Fimage.png?alt=media&amp;token=85750bcc-fd07-4bba-8228-f5ededdadc5b" alt="" width="501"><figcaption></figcaption></figure>

Les paramètres du champ *parameters* sont les mêmes que ceux de l'[API REST](#parametres-communs).

#### **Requêtes feedBack**

Comme avec l'API REST, aucune réponse n'est renvoyée pour les requêtes de satisfaction. Les valeurs des champs sont les mêmes que pour l'[API REST](#satisfaction).

### Requêtes du serveur

#### **Réponse à afficher**

Le serveur indique au client qu'un message a été envoyé par le bot ou par un opérateur humain. Ces messages peuvent arriver sans que l'utilisateur ait posé de question.

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FY9Iu0CkFDRySIE3zttYS%2Fimage.png?alt=media&amp;token=b7dd26cf-0ea0-4fa6-ac8a-3e2fc5275ddf" alt="" width="536"><figcaption></figcaption></figure>

Les champs sont les mêmes que dans la réponse de l'API REST, avec en plus le champ *human* : il vaut `true` si le message vient d'un opérateur humain.

#### **Notification**

Les notifications informent l'utilisateur sans remplacer la dernière réponse, par exemple pour lui indiquer que l'opérateur n'est plus connecté.

<figure><img src="https://1101559743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMQl4578l4DzuAEhrEii%2Fuploads%2FdFIwu3onJFB00Ca3iNFK%2Fimage.png?alt=media&amp;token=55b99ffd-f5dc-40f3-8206-c24942a28f12" alt="" width="529"><figcaption></figcaption></figure>
