Dialog API
Querying the dialog engine
The dialog engine can be queried by web services. Depending of what you are using, you must use either a web service in synchronous mode or a web service in asynchronous mode:
A dialog in synchronous mode implies that the dialog engine will only respond when asked by a user's question. In the sequence diagram below, the talk dialog requests are synchronous and the result contains the bot's answer;
A dialog in asynchronous mode implies that the dialog engine can send messages without having been requested. In the sequence diagram below, the feedback dialog requests are asynchronous and no feedback is expected.
Synchronous dialog web service
You can use the swagger interface available from Preferences > Api > API access. Click the link available and click Chat.
This web service is in REST mode, accessible via HTTP GET or HTTP POST.
Parameters
Here are the parameters of the queries to the web service:
Parameters | |
contextId | Dialog ID |
The response of the web service will contain, among others, the value to be later on given to this field to gather all the interactions in a single dialog. An interaction is part of a dialog only if they have the same contextID. On the server side, when the context ID is unused for 10 minutes, the dialog is archived and this ID is revoked. If an invalid or revoked context ID is sent to the web service, the server will ignore it and create a new valid context ID. This parameter is sent the first time by the server with the first query, then it has to be filled in the entry parameters for the next requests. | |
botUUID | Bot ID (Bot identification) |
| The bot ID can be found on the page Préférences > Api > API access. |
userInput | User Input) |
| This parameter contains the user question. Only the first 600 characters of the question are taken into account by the dialog engine. |
space | Consultation space |
| The consultation space to be used can be sent to the dialog box thanks to this parameter. So no consultation space is used over others, this parameters has to be set to Default. |
language | ISO code of the language (fr, en, nl) or language selection in swagger |
| The language parameter is useful when the bot is multilingual.This parameter shows the default language of the bot. If the user talks to the bot in another language that it can handle, it will answer anyway in the used language. |
alreadyCame | Information if user has already come |
| This parameter shows if the user has already come.The true value shows that the user has already come.. The false value shows that the user has never come before. |
clientId | User ID (User identification) |
| If this parameter is not filled in, the dialog will be anonymous.If this parameter is filled in, which can happen if the dialog box is used in a connected space of the website, this ID will be linked to the conversation. In the back office, on the dialog reading page, the user name will only be shown to admins. |
userUrl | User URL (User current url) |
| This parameter shows the URL from which the question was asked. |
browser | Browser |
| This parameter shows the browser used by the user. |
os | OS (Operating System) |
| This parameter shows the user's OS |
enableLanguageDetection | Language detection |
| This parameter shows if language detection is enabled.When set to true, language detection is enabled. When set to false, language detection is off. |
contextType | Dialog context |
| This parameter shows the the context of the dialog: |
- Web ; | |
- Vocal ; | |
- Android ; | |
- iOS. | |
qualificationMode | Qualification mode |
| This parameter shows if the questions asked to the bot are in qualification mode. By setting it to true, knowledge items are published and usable. Dialogs are not counted in the analytics. By setting it to false, only already published knowledge items can be used. Dialogs are counted in analytics. This setting is false by default. |
solutionUsed | Solution used |
| This parameter shows the type of solution used: assistant, livechat, etc. |
pureLiveChat | pureLiveChat |
| This parameter shows if the pureLiveChat option is enabled.If true, the option pureLivechat is enabled. If false, the option pureLivechat is disabled. |
extraParameters | Question type |
| This parameter shows the query is of a special type.By default, if no type is filled in, the query will be shown as entered by the user. |
It is useful if the bot has, for example, reworded and the user has clicked on one of the rewords, or if the answer contained clickable links (to another answer or a URL). This parameters lets you indicate the question is of a different type. | |
It has no influence on the processing by the dialog engine, but help identify the origin of requests in analytics. | |
The available types are: | |
- reword_auto: click on one of the rewords suggested by the bot if the question was misunderstood; | |
- redirection: click on a URL in a bot answer with opening in the same tab; | |
- redirection_newpage : click on a URL in a bot answer with opening in a new tab; | |
- redirection_javascript: click on a URL in a bot answer with launch of a Javascript(ex: escalation to Livechat); | |
- redirection_knowledge: click on a URL in a bot answer with opening of another knowledge; | |
- redirection_consultation_space : click on a link when the bot did not have an answer in the current consultation space and suggested to the user to visit another consultation space; | |
- redirection_personnality | |
- before_close_dialog | |
- reword_teaser | |
- exportable_faq | |
- reword_feedback | |
variables | context variables\ |
| This parameter allows to pass additional information to the bot. This information can then be used in the backoffice to give custom answers or answers that dependent of the use context. |
They have to be sent as follows: {"Key1":"value1","Key2":"value2"} | |
For example, if the following context variables have to be shared: | |
name: dupont | |
InvoiceSum: 123.45 | |
The contextVariables parameter will be: {"name":"dupont","InvoiceSum":"123.45"} | |
doNotRegisterInteraction | Information about dialog storage |
| Setting this parameter to true disables saving interactions.Setting this parameter to false enables saving interactions |
competency | Operator Competency |
| This parameter shows the used operator competency. |
timestamp | Time of the dialog |
| This parameter shows the time of the dialog. |
templateFormats | Template formats |
| This parameter shows used format templates. |
tag (ou tagID) | Tags |
| This parameter allows to include a tag.To insert the value of a tag, write in its name or tagID. To find the tagID of a tag: right click > inspect your subtag. Then, find the following code (for example): |
div id="tag-6671" | |
Here, the tagID is 6671. | |
period | Period |
| Allows to filter in a period. Possible values are: Today, Yesterday, Last7Days, CurrentMonth, LastMonth, Last30Days, Last3Months, Last6Months, Last12Months. |
| Allows to exclude or include the gallery to which your knowledge base is linked. Setting it to true excludes the gallery. Setting is to false includes the gallery. |
excludeGalleryContent | Exclude Gallery Content |
QueriesChat
Retrieve a dialog context ID
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | - alreadyCame |
- space | - clientId |
- language | - os |
- browser | |
- disableLanguageDetection | |
- ContextType | |
- qualificationMode | |
- solutionUsed | |
- pureLiveChat |
Curl request:
Body answer:
Retrieve the list of previous dialogs associated to a user
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | |
- solutionUsed | |
- clientId |
Curl request:
Body answer:
Send error
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | - browser |
- contextUUID | - os |
- solutionUsed | - stackTrace |
- error | - jsCreation |
- message | - userUrl |
Curl request:
Body answer:
Send satisfaction opinion
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- feedBack |
Curl request:
Send satisfaction without comment
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- comment |
Curl request:
Send dissatisfaction opinion with selected reason
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- choiceKey |
Curl request:
Save GDPR request
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | - language |
- clientId | |
- object | |
Curl request:
Body answer:
Retrieve dialog history
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- dialog |
|
Curl request:
Body answer:
Check if there is a new user answer (Livechat mode)
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- language | |
- space | |
- lastPoll |
|
Curl request:
Body answer:
Perform a search in a bot's knowledge:
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | - language |
- search | |
- searchInPersonalities |
Curl request:
Body answer:
Send an answer to a survey
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | - interactionSurveyAnswer |
- contextUUID | |
- solutionUsed | |
- fields |
Curl request:
Body answer:
Retrieve survey configuration
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- language | |
- surveyId |
|
Curl request:
Body answer:
Send interaction without context specification (start new context)
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | - userUrl |
- userInput | - alreadyCame |
- space | - clientId |
- language | - os |
- browser | |
- enableLanguageDetection | |
- contextType | |
- qualificationMode | |
- solutionUsed | |
- pureLiveChat | |
- extraParameters | |
- doNotRegisterInteraction | |
- competency | |
- timestamp | |
- templateFormats |
Curl request:
Body answer:
Send interaction with specific context
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | - userUrl |
- contextUUID | - alreadyCame |
- userInput | - clientId |
- space | - os |
- language | - browser |
- enableLanguageDetection | |
- contextType | |
- qualificationMode | |
- solutionUsed | |
- pureLiveChat | |
- extraParameters | |
- DoNotRegisterInteraction | |
- competency | |
- timestamp | |
- templateFormats |
Curl request:
Answer body:
Retrieve top used knowledge
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | - includeTagChildren |
- solutionUsed | - qualificationMode |
- language | - maxKnowledge |
- space | |
- period | |
- tag |
Note: you can also insert the tagID instead of the tag name (see details in parameter table).
Curl request:
Body answer:
Send information about content typed in by user
| Mandatory settings | Optional settings |
|---|---|
- botUUID | - typing |
- contextUUID | |
- solutionUsed | |
- content |
Curl request:
Body answer:
Insert of delete a context variable
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | |
- contextUUID | |
- solutionUsed | |
- name | |
- value |
|
Curl request:
Store a user visit
| Mandatory parameters | Optional parameters |
|---|---|
- botUUID | - qualificationMode |
- contextUUID | |
- solutionUsed | |
- language | |
- space |
Curl request:
Body answer:
Asynchronous dialog web service
The asynchronous web service works on the principle of websockets.
The protocol to use in websockets is named dyduchat.
This mechanism is especially useful when the user talks with an operator because then, the operator does not have to wait for a user's question to give an answer. They can speak first or send several messages to the user.
Customer requests
The client must send its requests in JSON format as described below:
Request talk**
The format of the request talk is as follows:
All field values must be base64 encoded.
The parameters in the parameters field are the same as those defined for the REST web service from the synchronous mode.
Requests feedBack**
As in synchronous mode, no feedback is expected for feedBack requests.
All field values must be base64 encoded.
The values of the fields are the same as those defined for the synchronous mode REST web service.
Positive / Negative satisfaction
Reason for dissatisfaction
Commentary of dissatisfaction
Server Requests
Answer to display
Requests sent by the server tell the client that a message has been issued by an automated bot or by a human operator.
They can be sent without the user having made a request.
All parameters except human are exactly the same as for the Synchronous Mode REST web service.
The new human field indicates that the message is from a human operator if it is true.
Notification
Notifications are used to inform the user of some elements without replacing the last answer.
They can, for example, inform the user that the human operator is no longer connected.
Last updated
