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 queryexcludeGalleryContent
: 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:
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:
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:
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:
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:
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:
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:
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.
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
Retrieving the value of this topic from the list of topics:
tags > id > value
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 targetingapicondition
: 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:
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:
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 astring
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.
Last updated