Links

FAQ statique

Configuration FAQ statique

Description Générale

Dans un but de construction d’un portail de connaissances ou d’une FAQ, il peut être intéressant de lister toutes les thématiques disponibles ou les sous-thématiques liées à une thématique parent ou encore faire référencer le contenu de la base de connaissances sur un moteur de recherche. Pour tous ces cas, la génération d’une FAQ statique est nécessaire.
Ce que nous appelons FAQ Statique est la génération d’information à partir d’un extrait de la base de connaissances à un instant précis, sans actualisation du contenu par une API en temps réel.

1- BotId

Pour appeler l’API, un BOTID est obligatoire. Ce botID est trouvable sur le BMS dans le menu Paramètres > API > Accès aux APIs. Chaque bot a son propre BotId.

2- Process

Afin de générer une FAQ Statique, qu’il s’agisse de simples thématiques, de sous-thématiques ou des connaissances, il est toujours nécessaire de travailler à partir du fichier XML de base de connaissances.
Pour cela, nous allons diviser l’explication des sections suivantes selon deux axes :
  • Le premier pour le téléchargement du fichier XML de base de connaissances
  • Le second pour l’analyse du fichier XML afin d’en ressortir les informations intéressantes (nom des thématiques, sous-thématiques, connaissances…)

3- Téléchargement du fichier XML

3.1. Endpoint URL

Le endpoint de l’API est présent sur chaque serveur :
https://<serveur>/servlet/api/bot/knowledgebase/export
L’URL se compose également de deux paramètres :
  • botUUID : ID du bot à interroger
  • excludeGalleryContent : valeur pour indiquer si la galerie doit être exportée dans le fichier XML ou non (true pour ne pas exporter la galerie ; false pour exporter la galerie)
Enfin, il est également nécessaire de passer un token d'autorisation. Ce token d’autorisation est calculé de manière classique selon la méthode HTTP Basic (https://en.wikipedia.org/wiki/Basic_access_authentication).
Les login et mots de passe dont vous aurez besoin pour calculer le token sont ceux du BMS de dydu, cela signifie que ce ne sont pas vos identifiants SSO si vous utilisez le SSO pour vous connecter au BMS.
Exemple :
curl -X GET
"https://<serveur>/servlet/api/bot/knowledgebase/export/<botId>/true" -H
"accept: application/xml" -H "Authorization: authorizationToken"

3.2. Retour de l'API

Si la requête est valide, l’API retourne un fichier au format XML.

3.3. Limites

L’export de base de connaissances est limité à un seul export simultané par utilisateur pour des raisons de performance.

4- Analyse du fichier XML

Le fichier XML de base de connaissances contient de nombreuses informations.
Dans les prochains paragraphes, nous ne traiterons que des balises suivantes :
  • tags
  • knowledgesGroups
Les autres balises du fichier XML ne sont pas couvertes par cette documentation.

4.1. Lister les thématiques

La liste des thématiques est contenue au sein de la balise “tags”. La balise “tags” est composée d’une ou plusieurs balises “tag”.
Chaque balise “tag” est composée de la façon suivante :
Nom du tag
Description
id
Une seule balise id est présente pour indiquer l’id interne de la thématique
tagValue
Il y a autant de balises tagValue que de langues définies dans le bot.
Chaque balise comporte 2 attributs :
  • language : La langue dans laquelle est définie le libellé
  • value : Libellé de la thématique dans la langue spécifiée
Exemple :
<tags>
<tag color="166da3">
<id>1357</id>
<tagvalue language="French" value="Nom de la thématique 1" translated="true"/>
<tagvalue language="English" value="Name of Tag #1" translated="true"/>
</tag>
<tag color="ffffff">
<id>1234</id>
<tagvalue language="French" value="Nom de la thématique 2" translated="true"/>
<tagvalue language="English" value="Name of Tag #2" translated="true"/>
</tag>
</tags>
Pour la liste des thématiques, il faut lister l’ensemble des balises “tag” et lire la balise “tagValue” pour la langue souhaitée.

4.2. Lister les sous-thématiques

La liste des thématiques et sous-thématiques est contenue au sein de la balise “tags”. La balise “tags” est composée d’une ou plusieurs balises “tag”.
Chaque balise “tag” est composée de la façon suivante :
Nom du tag
Description
id
Une seule balise id est présente pour indiquer l’id interne de la thématique
tagValue
Il y a autant de balises tagValue que de langues définies dans le bot.
Chaque balise comporte 2 attributs :
  • language : La langue dans laquelle est définie le libellé
  • value : Libellé de la thématique dans la langue spécifiée
tag
Il y a autant de balises “tag” que de sous-thématiques directes.
Chaque sous-thématique peut également contenir des sous-thématiques.
C’est une structure récursive.
Exemple :
<tags>
<tag color="166da3">
<id>1357</id>
<tagvalue language="French" value="Nom de la thématique 1" translated="true"/>
<tag color="1a2b3c">
<id>14890</id>
<tagvalue language="French" value="Nom de la thématique 3"/>
<tag color="000000">
<id>13567</id>
<tagvalue language="French" value="Nom de la thématique 4"/>
</tag>
</tag>
</tag>
<tag color="ffffff">
<id>1234</id>
<tagvalue language="French" value="Nom de la thématique 2" translated="true"/>
</tag>
</tags>
Pour la liste des thématiques et sous-thématiques, il faut lister l’ensemble des balises “tag” et de lire la balise “tagValue” pour la langue souhaitée.

4.3. Lister toutes les connaissances

L’ensemble des connaissances sont incluses dans le noeud “knowledgesGroups”. La balise “knowledgesGroups” contient autant de noeuds “knowledgesGroup” que de connaissances.
Chaque noeud de type “knowledgesGroup” est composé de la façon suivante :
Nom du tag
Description
conditions
Ensemble des conditions qui peuvent déclencher tout ou partie d’une connaissance (intentions, condition pour une réponse complémentaire …)
knowledges
Ensemble des réponses de la connaissance (il peut y avoir plusieurs blocs de réponses s’il y a un arbre de décision)
popularity
Valeur interne dydu.
Pour lister les connaissances, il est préférable de lister d’abord les réponses puis les conditions.
Pour cela, il faut parcourir l’ensemble des connaissances, c'est-à-dire les nœuds “knowledgesGroup”, puis parcourir les réponses, c'est-à-dire le noeud “knowledges” qui contient lui même des noeuds “knowledge”.
Pour lister toutes les connaissances, il faut appliquer la même procédure :
Etape fonctionnelle
Etape technique
1. Parcourir toutes les connaissances
1. Parcourir tous les noeuds “knowledgesGroup”
2. Parmi les blocs de réponses, identifier la réponse liée à la question “racine”
2.1 Au sein du noeud “knowledges”, parcourir tous les noeuds “knowledge”
2.2 Trouver le noeud “knowledge” ayant un seul noeud “condition”
3. Identifier la question “racine” associée
3.1 Noter l’ID du noeud “condition” identifié à l’étape précédente
3.2 Au sein du noeud “knowledgesGroup”, parcourir le noeud “conditions”
3.3 Au sein du noeud “conditions”, parcourir les noeuds “simplecondition”
3.4 Identifier le noeud “simplecondition” ayant le même ID que l’ID noté en 3.1
Exemple ci-dessous avec un noeud “knowledgesGroup”:
2.1 1 noeud “knowledge” trouvé
2.2 Le noeud “knowledge” contient un noeud “conditions” qui contient 1 seul noeud “condition”
3.1 Notons l’id 419891
3.2 1 seul noeud “conditions”
3.3 1 seul noeud “simplecondition”
3.4 Le noeud “simplecondition” dispose bien de l’id 419891
<knowledgesGroup deleteTreeBeforeImport="false">
<conditions>
<simplecondition id="419891" rewordable="true" followingRefocusForbidden="false" trigger="true" contextualTrigger="false" persistentId="287023" faqExport="false">
<conditionLanguage language="French" strict="false" optionalInFormulation="false" matchingType="None">
<reword>Arbre de décision</reword>
<sentences>
<string>Arbre de décision</string>
</sentences>
<keywords/>
<exclusions/>
<bounceConditions/>
</conditionLanguage>
</simplecondition>
</conditions>
<knowledges>
<knowledge id="419229">
<actions>
<action id="846322" garbageExclusive="false">
<url></url>
<botId>460</botId>
<status>PUBLISHED</status>
<sentence>Souhaitez vous consulter un arbre de décision ?</sentence>
<language>French</language>
<consultationSpace>754</consultationSpace>
<sidebarTitle></sidebarTitle>
</action>
</actions>
<conditions>
<condition id="419891"/>
</conditions>
<tagId>20337</tagId>
<creationTime>2020-10-05 17:16:48.0</creationTime>
<lastModificationTime>2020-10-05 17:16:48.0</lastModificationTime>
</knowledge>
</knowledges>
<popularity>0.0</popularity>
</knowledgesGroup>

4.4. Lister toutes les connaissances avec leur thématique

Dans les “actions” d’une connaissance, l’information de la thématique est présente via le “tagId”. Il est ensuite nécessaire via la liste des thématique d’associer cet Id au nom de la thématique pour récupérer la liste des connaissances avec leur thématique.
Exemple du tagId dans une connaissance :
knowledge > tagId
<knowledge id="408279">
<actions>
<action id="832305" garbageExclusive="false">
<url></url>
<botId>391</botId>
<status>PUBLISHED</status>
<lastModificationAccountId>558</lastModificationAccountId>
<lastModificationTime>2019-10-28 12:02:18.0</lastModificationTime>
<sentence>OK</sentence>
<ignoreInAnalytic>false</ignoreInAnalytic>
<language>French</language>
<allowOnInvalidDate>false</allowOnInvalidDate>
<complementaryAnswers/>
<lockTextField>false</lockTextField>
<keepPopinMinimized>false</keepPopinMinimized>
<consultationSpace>613</consultationSpace>
<sidebarTitle></sidebarTitle>
<sidebarContent></sidebarContent>
<sidebarWidth>500</sidebarWidth>
<sidebarHeight>410</sidebarHeight>
<stepIndex>0</stepIndex>
<templateData>{}</templateData>
<sidebarTemplateData>{}</sidebarTemplateData>
</action>
</actions>
<conditions>
<condition id="408943"/>
</conditions>
<tagId>9487</tagId>
<creationTime>2019-10-28 12:02:08.0</creationTime>
<lastModificationTime>2019-10-28 12:05:30.0</lastModificationTime>
</knowledge>
Récupération de la valeur de cette thématique dans la liste des thématique :
tags > id > value
<tags>
<tag color="166da3">
<id>8010</id>
<tagvalue language="French" value="_Livechat" translated="true"/>
<tagvalue language="Polish" value="_Livechat" translated="false"/>
</tag>
<tag color="c21473">
<id>9487</id>
<tagvalue language="French" value="Tests" translated="true"/>
<tagvalue language="Polish" value="Tests" translated="false"/>
</tag>
</tags>

5- Annexes

5.1. Groupes de formulations

Les groupes de formulations sont présents dans le noeud “matchingGroups” - il n’y a qu’un seul élément de ce type. Les catégories de groupes de formulations sont quant à elles présentes dans le noeud “matchingCategories” - il n’y a qu’un seul élément de ce type.
Voyons comment est structuré un groupe dans formulations dans le XML :
Chaque groupe de formulations est défini au sein d’un noeud “group”, qui contient :
  • Un attribut “externalId” : Id interne du groupe de formulation. C’est cet ID qui est utilisé dans la base de connaissance, par les formulations qui utilisent le groupe de formulations.
  • Un noeud “categories” :
    • Il contient un seul noeud de type “GroupCategoryMap” :
      • Il contient un seul noeud de type “categoryId” dont la valeur est l’ID de la categorie de groupe de formulations.
  • Un noeud “groupValues” :
    • Ensemble de noeuds de type “groupValue” qui défini le titre du groupe de formulations par langue.
    • Chaque “groupValue” contient deux attributs :
      • language : Langue dans laquelle est défini le titre
      • value : Titre du groupe de formulations
  • Un noeud “formulations” :
    • Ensemble de noeuds de type “formulation” qui défini une formulation d’un groupe de formulations
    • Chaque “formulation” contient plusieurs attributs, dont :
      • sentence : La formulation. Si la formulation contient elle même des groupes de formulations, seul l’ID de ces groupes sera présent
      • keyword : Défini si la formulation est de type keyword
      • language : Défini dans quelle langue est la formulation

5.2. Connaissances

5.2.1. Comprendre les conditions

La structure du noeud “conditions” est composée de différents noeuds :
  • simplecondition : noeuds de type intention simple (avec formulations, keywords, exclusions…)
  • pushcondition : noeuds de type condition pour le ciblage comportemental
  • apicondition : noeuds de type condition de contexte
Ces noeuds sont constitués des mêmes attributs mais un seul est important pour nous :
  • l’attribut “id” : il s’agit d’un ID interne qui permet de faire le lien entre les réponses que nous verrons plus tard et les conditions pour déclencher ces réponses.
Ces noeuds contiennent également d’autres noeuds de type “conditionLanguage”.
Il y a autant de noeud “conditionLanguage” qu’il y a de conditions par langues. Ils sont composés de la façon suivante :
Nom du tag
Description
Reword
Défini le titre de l’intention
Uniquement disponible pour simplecondition et pushcondition
sentences
Défini les formulations de l’intention. Ce noeud contient autant de noeuds “string” que de formulations
Non utilisé pour la FAQ Statique
Uniquement pour simplecondition
keywords
Défini les keywords de l’intention
Non utilisé pour la FAQ Statique
Uniquement disponible pour simplecondition
exclusions
Défini les exclusions de l’intention
Non utilisé pour la FAQ Statique
Uniquement disponible pour simplecondition
bounceConditions
Défini les conditions de rebond
Non utilisé pour la FAQ Statique.
Uniquement disponible pour simplecondition
optionalpart
Défini la condition de contexte (dans les noeuds “captureCondition”)
Non utilisé pour la FAQ Statique
Uniquement disponible pour apicondition

5.2.2.Comprendre les réponses

La structure du noeud “knowledges” est composée d’autant de noeuds “knowledge” qu’il y a de blocs de réponses dans la connaissance.
Chaque noeud “knowledge” est constitué des noeuds suivants :
  • actions : Noeud contenant les noeuds relatifs à la réponse
  • conditions : Noeud contenant les éléments qui déclenchent ce bloc de réponse
  • tagId : (facultatif) Indique l’id de la thématique parente
  • creationTime : Indique la date et l’heure de la création de ce bloc
  • lastModificationTime : Indique la date et l’heure de la dernière modification de ce bloc
Le noeud actions peut contenir les informations suivantes :
Nom du tag
Description
url
Url
status
Indique le statut de la réponse (Draft, Disabled, Published…)
sentence
Indique la réponse principale
language
Indique la langue de la réponse
consultationSpace
Indique l’id de l’espace de consultation
sidebarTitle
Indique le titre du panneau latéral s’il est défini
sidebarContent
Indique le contenu du panneau latéral s’il est défini
sidebarWidth
Indique la largeur du panneau latéral s’il est défini
sidebarHeight
Indique la hauteur du panneau latéral s’il est défini

5.2.3. Lister toutes les phrases générales

Les phrases générales sont présentes via le noeud botProfileAnswers.
Chaque phrase générale est défini dans un noeud “botProfileAnswer”, qui contient notamment :
  • Un élément “key” : Défini le type de la phrase générale. Il s’agit de valeurs internes dydu
  • Un élément “language” : Défini la langue de la phrase générale
  • Un élément “consultationSpace” : Défini l’ID de l’espace de consultation de la phase générale
  • Un élément “sentences” : Noeud contenant lui même un noeud “string” qui contient la phrase générale
On y retrouve notamment les réponses pour les cas : Réponse aux phrases incomprises (garbage) et Trop de phrases incomprises (toomanygarbages)

5.2.4. Lister toutes les préférences du bot

Les préférences d’un bot sont listées dans le noeud botPreferences.

5.2.5. Lister tous les espaces de consultation

Les espaces de consultation sont disponibles dans le noeud consultationSpaces.
Dernière mise à jour 2mo ago
Tous droits réservés @ 2023 dydu.