Boîte de dialogue API
Interrogation du moteur de dialogues
Le moteur de dialogues peut être interrogé par des services web. Selon l'usage, il faut utiliser soit un service web en mode synchrone, soit un service web en mode asynchrone :
Une conversation en mode synchrone implique que le moteur de dialogues ne donnera une réponse que lorsqu'il est sollicité par une question d'un utilisateur. Dans le diagramme de séquence ci-dessous, les requêtes de dialogue talk sont synchrones et le résultat contient la réponse du bot ;
Une conversation en mode asynchrone implique que le moteur de dialogues peut envoyer des messages sans avoir été sollicité. Dans le diagramme de séquence ci-dessous, les requêtes de dialogue feedback sont asynchrones et aucun retour n'est attendu.
Service web conversation asynchrone
Vous pouvez exploiter l'interface swagger disponible depuis la page des Préférences > Api > Accès aux APIs. Cliquez sur le lien disponible puis cliquez sur Chat.
Ce service web est en mode REST, accessible via HTTP GET ou HTTP POST.
Paramètres
Les paramètres des requêtes de ce service web sont les suivants :
Paramètres | |
contextId | ID du Dialogue |
Le retour du service web contiendra, entre autres, la valeur qu'il faudra par la suite donner à ce champ afin de regrouper toutes les interactions au sein d'une même conversation. Une interaction fait partie d'une conversation seulement si elles ont le même contextID. Côté serveur, lorsque l'ID de contexte est inutilisé pendant 10 minutes, le dialogue est archivé et cet ID est révoqué. Si un identifiant de contexte invalide ou révoqué est passé au service web, le serveur n'en tiendra pas compte et générera un nouvel identifiant de contexte valide. Ce paramètre est renvoyé la première fois par le serveur lors de la première requête puis il doit être renseigné dans les paramètres d'entrée pour les requêtes suivantes. | |
botUUID | ID du bot (Identifiant du Bot) |
| L'ID du Bot peut être trouvé sur la page Préférences > Api > Accès aux APIs. |
userlnput | Input de l'utilisateur |
| Ce paramètre contient la question de l'internaute. Seuls les 600 premiers caractères de la question sont pris en compte par le moteur de dialogue. |
space | Espace de consultation |
| L'espace de consultation à utiliser peut être envoyé à la boîte de dialogue grâce à ce paramètre. Ainsi, aucun espace de consultation n'est utilisé par rapport aux autres, ce paramètre doit être défini sur par défaut. |
language | Code ISO de la langue (fr, en, nl) ou sélection de la langue en swagger |
| Le paramètre language est utile lorsque le bot est multilingue. Ce paramètre indique la langue par défaut du bot. Si l'utilisateur parle au bot dans une autre langue qu'il peut gérer, il répondra de toute façon dans la langue utilisée. |
alreadyCame | Information if user has already come |
| Ce paramètre indique si l'utilisateur est déjà venu. La valeur true indique que l'utilisateur est déjà venu. La valeur false indique que l'utilisateur n'est jamais venu auparavant. |
clientId | ID utilisateur (Identification utilisateur) |
| Si ce paramètre n'est pas renseigné, la conversation sera anonyme. Si ce paramètre est renseigné, ce qui peut être effectué si la boîte de dialogue est utilisée depuis un espace connecté sur le site, alors cet identifiant sera associé à la conversation. Dans le back office, dans la page de lecture des conversations, le nom de l'utilisateur ne sera cependant affiché qu'aux profils administrateurs. |
userUrl | URL de l'utilisateur (URL actuelle de l'utilisateur) |
| Ce paramètre affiche l'URL à partir de laquelle la question a été posée. |
browser | Navigateur |
| Ce paramètre affiche le navigateur utilisé par l'utilisateur. |
os | OS (Système d'exploitation) |
| Ce paramètre affiche le système d'exploitation de l'utilisateur. |
enableLanguageDetection | Détection de la langue |
| Ce paramètre indique si la détection de la langue est activée. Lorsqu'elle est définie sur true, la détection de la langue est activée. Lorsqu'il est défini sur false, la détection de la langue est désactivée. |
contextType | Contexte du dialogue |
| Ce paramètre montre le contexte du dialogue : |
- Web ; | |
- Vocal ; | |
- Android ; | |
- iOS. | |
qualificationMode | Mode qualification |
| Ce paramètre indique si les questions posées au bot sont en mode qualification. En le définissant sur true, les éléments de connaissance sont publiés et utilisables. Les conversations ne sont pas comptabilisées dans les statistiques. En positionnant ce paramètre à false, seules les connaissances qui sont à l'état publié sont utilisables. Les conversations sont comptabilisées dans les statistiques. La valeur par défaut de ce paramètre est false. |
solutionUsed | Solution utilisée |
| Ce paramètre indique le type de solution utilisée : assistant, livechat, etc. |
pureLiveChat | pureLiveChat |
| Ce paramètre indique si l'option pureLiveChat est activée. Si true, l'option pureLivechat est activée. En positionnant ce paramètre à false, l'option pureLivechat est désactivée. |
extraParameters | Type de question |
| Ce paramètre est utile pour indiquer que la requête est d'un type particulier. Par défaut, si aucun type n'est renseigné, la requête sera considérée comme étant une entrée tapée par l'internaute. |
Il est utile si le bot a, par exemple, procédé à une reformulation et que l'internaute a cliqué sur l'une d'elles, ou bien si la réponse à la question contenait des liens cliquables (que ce soit pour aboutir à une autre réponse ou bien à une URL). Ce paramètre vous permet d'indiquer que la question est d'un type différent. | |
Cela n'a pas d'influence sur le traitement par le moteur de dialogue, mais cela permet de distinguer d'un point de vue statistique quelle est l'origine de la requête. | |
Les différents types disponibles sont : | |
reword_auto : clic sur une des reformulations proposées par le bot en cas d'incompréhension de la question ; | |
redirection : clic sur une URL contenue dans la réponse de le bot, et celle-ci s'est ouverte dans la même page ; | |
redirection_newpage : clic sur une URL contenue dans la réponse du bot, et celle-ci s'est ouverte dans un autre onglet ; | |
redirection_javascript : clic sur un lien contenu dans la réponse du bot, lien qui exécute du javascript (ex : escalade vers le Livechat) ; | |
redirection_knowledge : clic sur un lien contenu dans la réponse du bot qui affiche la réponse d'une autre connaissance ; | |
redirection_consultation_space : clic sur un lien lorsque le bot n'avait pas la réponse dans l'espace de consultation en cours, et qu'il a proposé à l'internaute d'obtenir la réponse en changeant d'espace de consultation ; | |
- redirection_personnality | |
before_close_dialog | |
- reword_teaser | |
- exportable_faq | |
- reword_feedback | |
variables | variables de contexte\ |
| Ce paramètre permet de transmettre des informations supplémentaires au bot. Ces informations peuvent ensuite être utilisées dans le backoffice pour donner des réponses personnalisées ou des réponses qui dépendent du contexte d'utilisation. |
Elles doivent être transmises de la manière suivante : clé1=valeur1,clé2=valeur2,clé3=valeur3,... | |
Par exemple, si les variables de contexte suivantes doivent être partagées : | |
name: dupont | |
InvoiceSum: 123.45 | |
Le paramètre contextVariables sera : {"name":"dupont","InvoiceSum":"123.45"} | |
doNotRegisterInteraction | Informations sur le stockage des boîtes de dialogue |
| La définition de ce paramètre sur true désactive la sauvegarde des interactions. La définition de ce paramètre sur false permet la sauvegarde des interactions. |
competency | Compétence de l'opérateur |
| Ce paramètre montre la compétence de l'opérateur. |
timestamp | Durée de la conversation |
| Ce paramètre montre la durée de la conversation. |
templateFormats | Modèles de format |
| Ce paramètre affiche les modèles de format utilisés. |
tag (ou tagID) | Thématiques |
| Ce paramètre permet d'inclure une thématique. Pour insérer la valeur d'une thématique, écrivez son nom ou tagID. Pour trouver le tagID de la thématique : clic droit > inspectez votre sous-thématique. Ensuite, trouvez le code suivant (par exemple) : |
div id="tag-6671" | |
Dans cet exemple, le tagID est 6671. | |
period | Période |
| Permet de filtrer dans une période. Les valeurs possibles sont : Today, Yesterday, Last7Days, CurrentMonth, LastMonth, Last30Days, Last3Months, Last6Months, Last12Months. |
| Permet d'exclure ou d'inclure la galerie à laquelle votre base de connaissances est liée. La valeur true exclut la galerie. La valeur false inclut la galerie. |
excludeGalleryContent | Exclure le contenu de la galerie |
Requêtes Chat
Récupérer un ID de contexte de dialogue
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | - alreadyCame |
- space | - clientId |
- language | - os |
- browser | |
- disableLanguageDetection | |
- ContextType | |
- qualificationMode | |
- solutionUsed | |
- pureLiveChat |
Requête curl :
Réponse body :
Récupérer la liste des boîtes de dialogue précédentes associées à un utilisateur
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | |
- solutionUsed | |
- clientId |
Requête curl :
Réponse body :
Envoyer une erreur
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | - browser |
- contextUUID | - os |
- solutionUsed | - stackTrace |
- error | - jsCreation |
- message | - userUrl |
Requête curl :
Réponse body :
Envoyer un avis de satisfaction
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- feedBack |
Requête curl :
Envoyer satisfaction sans commentaire
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- comment |
Requête curl :
Envoyer un avis d'insatisfaction avec la raison sélectionnée
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- choiceKey |
Requête curl :
Enregistrer la demande RGPD
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | - language |
- clientId | |
- object | |
Requête curl :
Réponse body :
Récupérer un historique de conversation
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- dialog |
|
Requête curl :
Réponse body :
Vérifier s'il y a une nouvelle réponse de l'utilisateur (Mode Livechat)
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- language | |
- space | |
- lastPoll |
|
Requête curl :
Réponse body :
Effectuer une recherche dans les connaissances d'un bot :
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | - language |
- search | |
- searchInPersonalities |
Requête curl :
Réponse body :
Envoyer une réponse à un questionnaire
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | - interactionSurveyAnswer |
- contextUUID | |
- solutionUsed | |
- fields |
Requête curl :
Réponse body :
Récupérer la configuration d'un questionnaire
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- language | |
- surveyId |
|
Requête curl :
Réponse body :
Envoyer une interaction sans spécification de contexte (initialiser un nouveau contexte)
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | - userUrl |
- userlnput | - alreadyCame |
- space | - clientId |
- language | - os |
- browser | |
- enableLanguageDetection | |
- contextType | |
- qualificationMode | |
- solutionUsed | |
- pureLiveChat | |
- extraParameters | |
- doNotRegisterInteraction | |
- competency | |
- timestamp | |
- templateFormats |
Requête curl :
Réponse body :
Envoyer une interaction avec un contexte spécifique
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | - userUrl |
- contextUUID | - alreadyCame |
- userlnput | - clientId |
- space | - os |
- language | - browser |
- enableLanguageDetection | |
- contextType | |
- qualificationMode | |
- solutionUsed | |
- pureLiveChat | |
- extraParameters | |
- DoNotRegisterInteraction | |
- competency | |
- timestamp | |
- templateFormats |
Requête curl :
Réponse body :
Récupérer les top connaissances utilisées
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | - includeTagChildren |
- solutionUsed | - qualificationMode |
- language | - maxKnowledge |
- space | |
- period | |
- tag |
Remarque : vous pouvez également insérer le tagID à la place du nom de la balise (voir les détails dans le tableau des paramètres).
Requête curl :
Réponse body :
Envoyer des informations à propos du contenu que l'utilisateur tape
| Paramètres nécessaires | Paramètres optionnels |
|---|---|
- botUUID | - typing |
- contextUUID | |
- solutionUsed | |
- content |
Requête curl :
Réponse body :
Insérer ou supprimer une variable de contexte
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- name | |
- value |
|
Requête curl :
Stocker une visite d'utilisateur
| Paramètres obligatoires | Paramètres optionnels |
|---|---|
- botUUID | - qualificationMode |
- contextUUID | |
- solutionUsed | |
- language | |
- space |
Requête curl :
Réponse body :
Service web conversation mode synchrone
Le service web asynchrone fonctionne sur le principe des websockets.
Le protocole à utiliser dans les websockets est nommé dyduchat.
Ce mécanisme est surtout utile dans un cas où l'utilisateur discute avec un opérateur humain, car dans ce cas l'opérateur n'a pas besoin d'attendre une question de l'utilisateur pour donner une réponse. Il peut parler de manière proactive, ou envoyer plusieurs messages de suite à l'utilisateur.
Requêtes client
Le client doit envoyer ses requêtes au format JSON telles que décrites ci-dessous :
Requête talk
Le format de la requête talk est le suivant :
Toutes les valeurs des champs doivent être encodées en base64.
Les paramètres du champ paramètres sont les mêmes que ceux définis pour le web service REST à partir du mode synchrone.
Requêtes feedBack
Tout comme pour le mode synchrone, aucun retour n'est attendu pour les requêtes de feedBack.
Toutes les valeurs des champs doivent être encodées en base64.
Les valeurs des champs sont les mêmes que celles définies pour le service web REST en mode synchrone.
Requêtes du serveur
Réponse à afficher
Les requêtes envoyées par le serveur indiquent au client qu'un message a été émis par un bot automatisé ou par un opérateur humain.
Ils peuvent être envoyés sans que l'utilisateur en ait fait la demande.
Tous les paramètres à l'exception de human sont exactement les mêmes que pour le service Web REST en mode synchrone.
Le nouveau champ human indique que le message provient d'un opérateur humain s'il est true.
Notification
Les notifications permettent d'informer l'utilisateur de certains éléments sans remplacer la dernière réponse.
Ils peuvent par exemple informer l'utilisateur que l'opérateur humain n'est plus connecté.
Dernière mise à jour
