Static FAQ

Static FAQ configuration

General Description

For the purpose of building a knowledge portal or an FAQ, it can be useful to list all available topics or subtopics related to a parent topic, or to reference the content of the knowledge base on a search engine. In all these cases, generating a static FAQ is necessary.

What we call a Static FAQ is the generation of information from an extract of the knowledge base at a specific point in time, without updating the content through a real-time API.

1 - BotID

To call the API, a BOTID is mandatory. This botID can be found on the BMS in the menu Settings > API > API Access. Each bot has its own BotID.

2 - Process

To generate a Static FAQ, whether it involves simple topics, subtopics, or knowledge, it is always necessary to work from the XML knowledge base file.

For this, we will divide the explanation of the following sections into two parts:

• The first for downloading the XML knowledge base file

• The second for analyzing the XML file to extract the relevant information (names of topics, subtopics, knowledge, etc.)

3 - Downloading the XML File

3.1 - Endpoint URL

The API endpoint is present on each server:

https://<server>/servlet/api/bot/knowledgebase/export

The URL also consists of two parameters:

• botUUID: ID of the bot to query

• excludeGalleryContent: value to indicate if the gallery should be exported in the XML file or not (true to not export the gallery; false to export the gallery)

Additionally, an authorization token is required. This authorization token is calculated in the usual way using the HTTP Basic method (https://en.wikipedia.org/wiki/Basic_access_authentication).

The login and password you need to calculate the token are those for the dydu BMS, meaning they are not your SSO credentials if you use SSO to log in to the BMS.

Example:

curl -X GET
 "https://<serveur>/servlet/api/bot/knowledgebase/export/<botId>/true" -H 
 "accept: application/xml" -H  "Authorization: authorizationToken"

3.2 - API Response

If the request is valid, the API returns a file in XML format.

3.3 - Limitations

Knowledge base export is limited to a single simultaneous export per user for performance reasons.

4 - Analysis of the XML File

The XML knowledge base file contains extensive information.

In the following paragraphs, we will focus only on the following tags:

• <tags>

• <knowledgesGroups>

Other tags in the XML file are not covered in this documentation.

4.1 - Listing the Topics

The list of topics is contained within the <tags> tag. The <tags> tag consists of one or more <tag> tags.

Each <tag> tag is structured as follows:

Tag name	Description
ID	Only one <id> tag is present to indicate the internal ID of the tag/topic.
tagValue	There are as many <tagValue> tags as there are languages defined in the bot. Each tag has 2 attributes: language: The language in which the label is defined. value: The label of the topic in the specified language.

Example:

<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>

For the list of topics, you need to list all the <tag> tags and read the <tagValue> tag for the desired language.

4.2 - Listing the Subtopics

The list of topics and subtopics is contained within the <tags> tag. The <tags> tag consists of one or more <tag> tags.

Each <tag> tag is structured as follows:

Tag name	Description
ID	Only one <id> tag is present to indicate the internal ID of the topic.
tagValue	There are as many <tagValue> tags as there are languages defined in the bot. Each <tagValue> tag has 2 attributes: language: The language in which the label is defined. value: The label of the topic in the specified language.
tag	There are as many <tag> tags as there are direct subtopics. Each subtopic can also contain further subtopics. It's a recursive structure.

Example:

<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>

For listing topics and subtopics, you need to iterate through all the <tag> tags and read the <tagValue> tag for the desired language.

4.3 - Listing All Knowledge Items

All knowledge items are included within the <knowledgesGroups> node. The <knowledgesGroups> tag contains as many <knowledgesGroup> nodes as there are knowledge items.

Each <knowledgesGroup> node is structured as follows:

Tag name	Description
conditions	Set of conditions that can trigger all or part of a knowledge item (intents, conditions for a supplementary response, etc.).
knowledges	Set of responses for the knowledge item (there can be multiple response blocks if there is a decision tree).
popularity	Internal value for dydu.

To list the knowledge items, it's preferable to first list the responses and then the conditions.

To do this, you need to iterate through all the knowledge items, which are the "knowledgesGroup" nodes, and then iterate through the responses, which are within the "knowledges" nodes that contain individual "knowledge" nodes.

You should apply the same procedure to list all knowledge items:

Functional Step	Technical Step
Browse all knowledge	Browse through all "knowledgesGroup" nodes.
Among the response blocks, identify the response related to the "root" question.	2.1. Within the "knowledges" node, iterate through all "knowledge" nodes. 2.2. Find the "knowledge" node that has exactly one "condition" node.
Identify the associated "root" question.	3.1. Note the ID of the "condition" node identified in the previous step. 3.2. Within the "knowledgesGroup" node, iterate through the "conditions" node. 3.3. Inside the "conditions" node, iterate through the "simplecondition" nodes. 3.4. Identify the "simplecondition" node that has the same ID as noted in 3.1.

Here is the example with a "knowledgesGroup" node:

2.1. Found 1 "knowledge" node.

2.2. The "knowledge" node contains a "conditions" node that contains exactly 1 "condition" node.

3.1. Let's note the ID 419891.

3.2. There is 1 "conditions" node.

3.3. There is 1 "simplecondition" node.

3.4. The "simplecondition" node indeed has the 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 - List all knowledge items with their corresponding topic

In the "actions" of a knowledge item, the topic information is present via the "tagId". It is then necessary to associate this ID with the topic name from the list of topics to retrieve the list of knowledge items with their corresponding topics.

Example:

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>

Retrieving the value of this topic from the list of topics:

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 - Formulation Groups

Here is the structure of a formulation group in XML:

Each formulation group is defined within a <group> node, which includes:

• An attribute externalId: the internal ID of the formulation group. This ID is used in the knowledge base by formulations that utilize the formulation group.

• A <categories> node:

  • It contains a single node of type <GroupCategoryMap>:

    • It contains a single node of type <categoryId> whose value is the ID of the formulation group category.

• A <groupValues> node:

  • Collection of <groupValue> nodes that define the title of the formulation group by language.

  • Each <groupValue> has two attributes:

    • language: the language in which the title is defined.

    • value: the title of the formulation group.

• A <formulations> node:

  • Collection of <formulation> nodes that define a formulation within a formulation group.

  • Each <formulation> has several attributes, including:

    • sentence: the formulation. If the formulation itself contains formulation groups, only the IDs of those groups will be present.

    • keyword: indicates if the formulation is a keyword type.

    • language: specifies the language of the formulation.

5.2 - Knowledge

5.2.1 - Understanding the Conditions

The structure of the "conditions" node consists of various types of nodes:

• simplecondition: nodes representing simple intents (including formulations, keywords, exclusions...)

• pushcondition: nodes representing conditions for behavioral targeting

• apicondition: nodes representing context conditions

These nodes share the same attributes, but one attribute is particularly important for us:

• The "id" attribute: this is an internal ID that links the responses we will see later with the conditions required to trigger these responses.

These nodes also contain other nodes of type "conditionLanguage".

There are as many "conditionLanguage" nodes as there are conditions per language. Here is their structure:

Tag name	Description
Reword	Define the title of the intent. Only available for simplecondition and pushcondition.
sentences	Define the formulations of the intent. This node contains as many "string" nodes as there are formulations. Not used for Static FAQ. Only for simplecondition.
keywords	Define the keywords of the intent. Not used for Static FAQ. Available only for simplecondition.
exclusions	Define the exclusions of the intent. Not used for Static FAQ. Available only for simplecondition.
bounceConditions	Define the bounce conditions. Not used for Static FAQ. Available only for simplecondition.
optionalpart	Define the context condition (in the "captureCondition" nodes). Not used for Static FAQ. Available only for apicondition.

5.2.2 - Understanding the Responses

The structure of the "knowledges" node consists of as many "knowledge" nodes as there are response blocks in the knowledge base.

Each "knowledge" node is composed of the following elements:

• actions: Node containing elements related to the response.

• conditions: Node containing the elements that trigger this response block.

• tagId: (Optional) Indicates the ID of the parent topic.

• creationTime: Indicates the date and time of creation of this block.

• lastModificationTime: Indicates the date and time of the last modification of this block.

The actions node can contain the following information:

Tag name	Description
url	Url
status	Indicate the status of the response (Draft, Disabled, Published...).
sentence	Indicate the main response.
language	Indicate the language of the response.
consultationSpace	Indicate the consultation space ID.
sidebarTitle	Indicate the title of the sidebar if it is defined.
sidebarContent	Indicate the content of the sidebar if it is defined.
sidebarWidth	Indicate the width of the sidebar if it is defined.
sidebarHeight	Indicate the height of the sidebar if it is defined.

5.2.3 - List all general sentences

General sentences are present via the botProfileAnswers node.

Each general sentence is defined within a botProfileAnswer node, which includes:

• An element key: Defines the type of the general sentence. These are internal values in dydu.

• An element language: Defines the language of the general sentence.

• An element consultationSpace: Defines the ID of the consultation space for the general sentence.

• An element sentences: Node containing a string node that contains the general sentence.

This includes responses for cases such as: Response to unclear sentences (garbage) and Too many unclear sentences (toomanygarbages).

5.2.4 - List all bot preferences

The preferences of a bot are listed in the botPreferences node.

5.2.5 - List all consultation spaces

Consultation spaces are available within the consultationSpaces node.