Conversational

In questa sezione

1

Workflow

Vai alla sezione→

2

1 - Define user Id

Vai alla sezione→

3

2 - Get bot info

Vai alla sezione→

4

3 - History messages

Vai alla sezione→

5

4 - Conversate

Vai alla sezione→

6

5 - Engagement

Vai alla sezione→

7

6 - Upvote an answer

Vai alla sezione→

8

7 - Downvote an answer

Vai alla sezione→

---

Algho allows you to build your own custom client that communicates with the conversational API. You can create your own web client, mobile or integrated into existing applications.

Workflow

The workflow consists of six steps:

1. Assign user Id
2. Get bot info to retrieve settings like language, welcome message, etc..
3. Get history messages for user (optional)
4. Send text message and receive response
5. Engagement (optional)
6. Upvote or downvote the bot answer (optional)

Some fields are not documented because they are not necessary for the implementation of a client and may be changed in the future. Only documented fields should be used because others remained for backward compatibility and will be removed in future updates.

API Endpoints

Use the correct endpoint based on your Algho account.

Server	Url
Qplus	https://virtualassistant.qplus.ai/api
AlghoOnCloud	https://virtualassistant.alghoncloud.com/api

Common call response

All calls return the following JSON fields structure:

Field	Description	Type
botId	bot id identifier	string
responseType	response type 'OK': success, 'KO': error	string
messageCode	message code	string
message	error or operation	string
serverTime	server time	datetime
value	data result	object

The value field contains the response data of the call to the API.

Example

{
  "botId" : "0b76f9173c941284f566a2460c7efeb5",
  "message" : "",
  "responseType" : "OK",
  "messageCode" : "OK",
  "value" : {...},
  "serverTime" : "2019-11-18 17:40:13"
}

1 - Define user Id

All APIs must be supplied with the user_id field. User Id must be unique for users, and must be generated.

Do not use incremental numeric values for security reason.

It is suggested to use a prefix that indicates the name of the application or client developed.

You can save user_id in a cookie if you are developing a web application or with another system if the application is not web.

Example

e43e69e1bbaf23962e04998d26d6798a828d5359c832e0d699f5fce6b0dd019b26e0d04f560b62f3abd7e948336bc494

2 - Get bot info

You can retrieve bot info from API

Method: GET
Url: /api/bot/{bot_id}?user_id={user_id}&bot_group_id={bot_group_id}&lang={lang}

Request params

Field	Description	Type
bot_id	bot id (optional)	string
user_id	user id (optional)	string
bot_group_id	bot group id (optional)	int
lang	bot language desired (optional)	string

Response structure

Field	Description	Type
country	bot country	string
standByMessage	standby message	string
downvoteSelfLearning	if true, downvote self learning is active	boolean
welcomeVideo	welcome video url	string
voting	if true, answer voting is active	boolean
emotionalAnalysis	if true, emotional analysis is enabled	boolean
ownerId	bot owner identifier	string
hasConversationItems	user has conversate with bot in previous time	boolean
callToAction	array of call to actions (eg. website url, phone number, email address)	array
useContextEnabled	if true, context analysis is enabled	boolean
noHistory	history disabled	boolean
options	array of questions used as welcome suggestions see table	array
welcomeBackMessage	welcome back message	string
standBy	bot is in stand by mode	boolean
showAvatarImage	if true, avatar image should be shown	boolean
name	bot name	string
poweredBy	message to show in the footer (if needed)	string
useContext	number of sentences considered as context	int
engagementTime	seconds to wait before call engagement from last request	int
gender	f female, m male	string
description	bot description	string
headerColor	header color (in rgb format)	string
pageBackground	background color (in rgba format)	string
botId	bot id identifier	string
lang	bot language (see table)	string
upvoteSelfLearning	if true, upvote self learning is active	boolean
emotionalModuleDescription	emotional module description	string
welcomeMessage	welcome message to show	string
licenseEnabled	license of the bot is in enabled	boolean
createTime	bot creation datetime	datetime
avatarImage	avatar image url	string

Details

Example

Request:

GET https://virtualassistant.alghoncloud.com/api/bot/0b76f9173c941284f566a2460c7efeb5?user_id=e43e69e1bbaf23962e04998d26d6798a828d5359c832e0d699f5fce6b0dd019b26e0d04f560b62f3abd7e948336bc494

Response:

Content-Type: application/json
Body:
{
    "responseType": "OK",
    "messageCode": "OK",
    "serverTime": "2022-02-23 11:30:57",
    "botId": "0b76f9173c941284f566a2460c7efeb5",
    "message": "Bot found",
    "value": {
        "country": "IT",
        "standByMessage": "<p> Questo è il mio nuovo messaggio di standby. </p>",
        "downvoteSelfLearning": false,
        "customAudio": false,
        "welcomeVideo": "",
        "voting": true,
        "emotionalAnalysis": true,
        "narrationMessage": "<p>Vuoi che descriva il prodotto?</p>",
        "ownerId": "8234gf380r12480r7823gt4r",
        "showActivationDays": false,
        "hasConversationItems": false,
        "callToAction": {
            "website": "",
            "operator": false
        },
        "useContextEnabled": false,
        "noHistory": false,
        "features": {
          "summarization": false,
            "livechat": true,
            "booking": false,
            "vocalAssistant": true,
            "bi": true,
            "tourverse": false,
            "nlg": false,
            "telegram": true,
            "textAssistant": true,
            "learning": true,
            "emotionalAnalysis": true,
            "livechatZendesk": false,
            "digitalHumanInterface": true,
            "dynamics": true,
            "rss": false,
            "zendesk": true,
            "messenger": true,
            "smartDocumentAccess": true,
            "voip": true,
            "mailbot": false,
            "kioskBanner": true,
            "licenseId": "cbed1eb5c77f8f8bc18a1566fe20e489",
            "magento": true,
            "kiosk": true,
            "n8n": false
        },
        "voiceId": "it-IT-Wavenet-C",
        "limitsExceded": false,
        "options": [
            {
                "optionType": "NextQuestion",
                "optionId": "176356",
                "optionText": "cosa sai fare?",
                "nextQuestionType": "QA"
            }
        ],
        "welcomeBackMessage": "<p>Ciao! Bentornato!</p>",
        "lookStyleId": "0",
        "operatorUnavalaibleMessage": "<p>Al momento i nostri operatori sono occupati. Riprova più tardi.</p>",
        "requestOperatorInMessage": "",
        "standBy": false,
        "operatorDisconnectMessage": "<p>Si è ora in contatto con il chatbot.</p>",
        "showAvatarImage": false,
        "operatorSelfLearning": false,
        "rejectToCallWithOperatorMessage": "",
        "narrationRules": [],
        "paragraphDelayString": "MEDIUM",
        "meta": {},
        "name": "Gaia",
        "poweredBy": "",
        "useContext": 0,
        "engagementTime": 60,
        "gender": "m",
        "disambiguationMessageWithSuggestions": "Potresti aiutarmi a capire meglio cosa ti interessa? Scegli tra queste possibilità",
        "description": "",
        "narrationNotAvailableMessage": "Mi dispiace, non sono ancora in grado di leggere questa pagina",
        "headerColor": "rgb(56, 171, 222)",
        "pageBackground": "rgba(55, 55, 55, 0.95)",
        "stopWordsSize": 0,
        "botId": "ab1b3fb73632eca762d9789b5d130484",
        "lang": "it",
        "paragraphDelay": "MEDIUM",
        "upvoteSelfLearning": false,
        "emotionalModuleDescription": "Da definire",
        "disambiguationMessageWithoutSuggestions": "Verifica se ciò che mi chiedi è tra questi suggerimenti",
        "disengageMessage": "",
        "welcomeMessage": "",
        "operatorConnectMessage": "<p>Si è ora in contatto con un operatore.</p>",
        "licenseEnabled": false,
        "banner": false,
        "speech": false,
        "createTime": "2021-10-06 17:18:49",
        "avatarImage": "https://staging-builder.alghoncloud.com/img/avatar/1.png",
        "narration": 0,
        "bannerRandom": false
    }
}

Not all fields are necessarily present

3 - History messages

if noHistory is false or hasConversationItems is true, you can retrieve user history messages.

method: GET
url: /api/conversate_item/list?bot_id={bot_id}&user_id={user_id}&conversation_id={conversation_id}&answer_id={answer_id}&offset={offset}&step={step}&sort={sort}

Request params

Field	Description	Type
bot_id	bot id (required)	string
user_id	user id (required)	string
conversation_id	conversation id (optional)	int
answer_id	answer id (optional)	int
offset	start position (optional)	int
step	numbers of items (optional)	int
sort	sort order (optional) see table	string

Response field

Field	Description	Type
date	message datetime	datetime
currentUrl	integration site page url	string
questionId	question id	int
conversationId	conversation id	int
responseTime	response time (in millis)	int
ip	IP address of the client from which the conversation originated	string
source	source type see table	string
conversationItemId	conversation item id	int
userId	user id	string
userQuestion	user question	string
questionText	question text	string
callType	call type (standard or sandbox for sandbox mode)	string
botMessageType	bot message type see table	string
botMessageId	bot message id	string
sourceType	custom app name (not to be confused with source)	string
inputMode	input mode see table	string
options	Array of options (suggestions or admissible values) see table	array
botMessageText	bot response text	string
botId	bot id	string
fieldType	field type object see table	object
questionType	question type see table	string

Sort option

Code	Description
conversation_item_id	order by conversationItemId (ascending)
conversation_item_id DESC	order by conversationItemId (descending)

Details

Example

Request:

GET https://virtualassistant.alghoncloud.com/api/conversate_item/list?bot_id=0b76f9173c941284f566a2460c7efeb5&user_id=e43e69e1bbaf23962e04998d26d6798a828d5359c832e0d699f5fce6b0dd019b26e0d04f560b62f3abd7e948336bc494&sort=conversation_item_id+DESC&offset=0&step=2

Response:

Content-Type: application/json
Body:
{
    "responseType": "OK",
    "messageCode": "OK",
    "serverTime": "2022-03-02 10:47:00",
    "message": "0b76f9173c941284f566a2460c7efeb5",
    "value": [
        {
            "date": "2022-02-23 12:29:37",
            "currentUrl": "https://staging-fe.alghoncloud.com/text/?bot=0b76f9173c941284f566a2460c7efeb5",
            "questionId": "123776",
            "conversationId": 121990,
            "responseTime": 381,
            "ip": "10.0.0.1",
            "source": "text_landscape",
            "conversationItemId": 331675,
            "userId": "e43e69e1bbaf23962e04998d26d6798a828d5359c832e0d699f5fce6b0dd019b26e0d04f560b62f3abd7e948336bc494",
            "userQuestion": "ciao",
            "questionText": "Ciao. Buongiorno. Salve. Buonasera",
            "callType": "standard",
            "botMessageType": "QA",
            "botMessageId": "202612",
            "sourceType": "web",
            "inputMode": "keyboard",
            "options": [],
            "botMessageText": "Ciao",
            "botId": "0b76f9173c941284f566a2460c7efeb5",
            "fieldType": {
                "suggestGlobalSearch": false,
                "suggestPreviousValues": false,
                "name": "Bool",
                "type": "BoolFieldType",
                "fieldTypeId": 5,
                "sensible": false
            },
            "questionType": "STANDARD"
        },
        {
            "date": "2022-02-23 12:29:37",
            "currentUrl": "https://staging-fe.alghoncloud.com/text/?bot=0b76f9173c941284f566a2460c7efeb5",
            "questionId": "123776",
            "conversationId": 121990,
            "ip": "10.0.0.1",
            "source": "text_landscape",
            "conversationItemId": 331676,
            "userId": "e43e69e1bbaf23962e04998d26d6798a828d5359c832e0d699f5fce6b0dd019b26e0d04f560b62f3abd7e948336bc494",
            "callType": "standard",
            "botMessageType": "FORM",
            "sourceType": "web",
            "inputMode": "keyboard",
            "options": [
                {
                    "optionType": "AdmissibleValue",
                    "optionValue": "SI",
                    "id": "",
                    "optionText": "SI"
                },
                {
                    "optionType": "AdmissibleValue",
                    "optionValue": "NO",
                    "id": "",
                    "optionText": "NO"
                },
                {
                    "optionType": "SkipValue",
                    "optionValue": "Avanti",
                    "optionText": "Avanti"
                },
                {
                    "optionType": "EndValue",
                    "optionValue": "Interrompi la compilazione",
                    "optionText": "Interrompi la compilazione"
                }
            ],
            "botMessageText": "<p>form test</p>",
            "botId": "0b76f9173c941284f566a2460c7efeb5",
            "fieldType": {
                "suggestGlobalSearch": false,
                "suggestPreviousValues": false,
                "name": "Bool",
                "type": "BoolFieldType",
                "fieldTypeId": 5,
                "sensible": false
            },
            "questionType": "STANDARD"
        }
    ]
}

Question type

Type	Description
STANDARD	standard
SLIDESHOW	slideshow (image carousel)

4 - Conversate

Allow to comunicate with bot.

Method: POST
Content-Type: application/json
alghoToken: MTIzNDU2Nzg5MA==
Url: /api/conversate_item/send_message?tts={tts}&lipSync={lipSync}

HTTP Request headers

Field	Description	Type
alghoToken	any custom context data in base64	string

Request params

Field	Description	Type
tts	tts response type (optional, default: NONE__) see table	string
lipSync	if true, show lip sync data (optional, default: false__)	boolean

info

The behavior of tts and lipSync parameters depends on the source field of JSON body.

JSON Request fields

Field	Description	Type
userId	user id	string
botId	bot id identifier	string
sourceType	custom app name (not to be confused with source)	string
conversationId	conversation id (first call: null)	int
currentUrl	url where bot is integrated	string
question_text	text to send (required) Max lenght: 1000	string
questionId	question id of clicked option (-1 default)	int
command	command code of clicked option (if present) see table	string
inputMode	input mode see table	string
source	source type see table	string
callType	call type (standard or sandbox for sandbox mode)	string
optionType	option type of clicked option see table	string
applicationContext	application context (used for targeted answers)	string
disableFieldHistory	for form answers, if true, field suggestions from conversation history are disabled	string
wsBasePath	url base for Algho Forms (optional)If present, it will be used to compose the final url by combining it with the relative one saved on the forms/fields.	string

After first call you can retrieve questionId value to pass to next call.

Details

Example

Request:

Method: POST
Url: https://virtualassistant.alghoncloud.com/api/conversate_item/send_message
alghoToken: MTIzNDU2Nzg5MA==
Content-Type: application/json
Body:
{
   "userId": "e43e69e1bbaf23962e04998d26d6798a828d5359c832e0d699f5fce6b0dd019b26e0d04f560b62f3abd7e948336bc494",
   "botId": "0b76f9173c941284f566a2460c7efeb5",
   "sourceType": "web",
   "conversationId": null,
   "currentUrl": "https://virtualassistant.alghoncloud.com/?bot=0b76f9173c941284f566a2460c7efeb5",
   "question_text": "come stai?",
   "questionId": -1,
   "command": "",
   "callType": "standard",
   "inputMode": "keyboard",
   "source": "text_landscape",
   "disableFieldHistory": false,
   "applicationContext": null,
   "wsBasePath": null,
   "optionType": "NextQuestion"
}

Response:

Content-Type: application/json
Body:
{
  "botId" : "0b76f9173c941284f566a2460c7efeb5",
  "message" : "",
  "responseType" : "OK",
  "messageCode" : "OK",
  "value" : {
    "conversationId" : 104276,
    "question" : "Hi. Good morning.",
    "userQuestionText" : "Hi",
    "questionId" : "68659",
    "solrScore" : 1.2242327,
    "score" : 0.5519999999999999,
    "baseQA" : true,
    "botId" : "0b76f9173c941284f566a2460c7efeb5",
    "answerList" : [ {
      "answerId" : "106049",
      "answerText" : "Hi",
      "order" : 0,
      "answerType" : "QA",
      "options" : [ {
        "optionText" : "What can you do?",
        "optionId" : "68645",
        "nextQuestionType" : "QA",
        "optionType" : "NextQuestion"
      }, {
        "optionText" : "What can I ask you?",
        "optionId" : "68663",
        "nextQuestionType" : "QA",
        "optionType" : "NextQuestion"
      }, {
        "optionText" : "What can you talk about?",
        "optionId" : "68668",
        "nextQuestionType" : "QA",
        "optionType" : "NextQuestion"
      } ],
      "insertTime": "2021-10-06 17:19:01",
      "updateTime": "2022-01-19 16:23:30",
      "ttsAnswerList" : [ {
        "htmlText" : "<p>Hi. Good morning.</p>",
        "plainText" : "Hi. Good morning.",
        "ssmlText" : "<speak> \n <p>Hi. Good morning.</p> \n</speak>"
      } ],
      "questionId" : "68659",
      "enableSuggestions": "common"
    } ],
    "answerType" : "QA",
    "questionType": "STANDARD"
  },
  "conversationId" : 104276,
  "serverTime" : "2019-11-18 17:40:13"
}

info

The answer text of the bot is in HTML and must be converted to plain text using regular expressions if the developed client is not web.

Response field

Field	Description	Type
conversationId	Conversation Id	int
question	bot question match	string
userQuestionText	user question text	string
questionId	bot question match id	int
score	affinity score between user question and bot question	int
baseQA	if true, this is base bot question	boolean
botId	bot id	string
answerList	Array of response see table	array
answerType	answer type see table	string
command	command code (optional) see table	string
frontEndMessage	front end message code (optional) see table	string
questionType	question type (optional) see table	string

Answer object

Field	Description	Type
answerId	answer id	string
answerText	answer text in html	string
media	media url (optional)	string
mediaType	media type (optional) see table	string
order	sort order (zero based)	int
answerType	answer type see table	string
options	array of options (suggestions) see table	array
field	field object if answerType equal FORM (optional) see table	array
payload	Custom command (used for browser automation, voip commands)	string
insertTime	bot question insert time (optional)	datetime
updateTime	bot question update time (optional)	datetime
ttsAnswerList	array of tts data for the answer (optional) see table	array
questionId	question id	int

Option object

Field	Description	Type
optionText	option text	string
optionId	option id	string
nextQuestionType	next question type see table	string
optionType	option type see table	string
suggestionType	suggestion type see table (optional)	string
command	command code see table (optional)	string

Field object

Field	Description	Type
fieldTemplateId	field template id	int
fieldType	field type object see table	object
formTemplateId	field template id	int
ownerId	owner identifier	string
name	field name	string
questionText	question text (used to introduce the field)	string
order	sort order (zero based)	int
required	field is required	boolean
maxValuesToSelect	max values to select	int
requiredByEtl	if true, field is required by ETL flow	boolean
deletable	if true, field is deletable	boolean
avSemanticMatch	if true, semantic match is active	boolean
forceValidation	if true, validation is also forced for fields that usually do not require it	boolean
validationRegex	regex used for field validation	string
entitiesAutofill	if true, autofill for entities is active	boolean
disableWriting	if true, free writing must not be allowed	boolean
skipSemanticValidation	if true, semantic validation will be skipped for this field value	boolean

Field type object

Field	Description	Type
fieldTypeId	field type id	int
name	field type name	string
type	field type enum see table	string
suggestPreviousValues	if true, previous values could be used as suggested values	boolean
sensible	if true, this field contains sensitive data	boolean

TTS object

Field	Description	Type
htmlText	answer text with tags	string
plainText	answer text without tags (plain)	string
ssmlText	answer text with ssml tags	string
audioUrl	url of generated audio file	string
lipSyncData	lip sync data	object

Answer type

Type	Name	Description
QA	Answer	answer found in the knowledge base
QB	Quibble	circumstance answers for questions to which the chatbot has no answer
QE	Engagement	message of engagement
FORM	Form	message asking to provide the value for a form field
RQ	Resume QA	message displayed when the user resume conversation after 15 minutes of inactivity
TR	Training	message displayed when the knowledge base is in a training state
SB	Stanby	answer returned when the bot is in stanby mode
SM	Sorry	answer returned when a user downvote an answer

NextQuestion type

Type	Description
QA	Answer
FORM	Form

Option Type

Type	Description
NextQuestion	next question to ask
AdmissibleValue	form admissible value for field
SuggestedValue	form suggested value for field
SkipValue	skip form field if is not required
EndValue	terminate form
Downvote	used if the voting function is active (voting feature)

Suggestion type

Type	Description
SuggestedValue	is suggested value to highlight (value previously used)

Command code

Code	Description
WS_NEXT_PAGE	allow to call form submit for next results (pagination)
SDA_SEARCH	allow to call sda search for results
SDA_NEXT_PAGE	allow to call sda for next results (pagination)
ETL_NEXT_PAGE	allow to call etl for next results (pagination)

info

The command type must be retransmitted in the conversation calls if present in the option clicked.

The command types can be expanded in the future.

InputMode type

Type	Description
clicked	click (selection of suggested or admissible value)
keyboard	keyboard
vocal	vocal

Source type

Type	Description
text_embedded	text version of an embedded script
voice_embedded	voice version of an embedded script
dhi_embedded	dhi version of an embedded script
text_landscape	text version of a fullscreen app
voice_landscape	voice version of a fullscreen app
dhi_landscape	dhi version of a fullscreen app
kiosk	kiosk mode (reserved)
custom	use this value for custom integrations
unknown	unknown source
social	integration with social networks (eg. Telegram, Messenger, etc.)
voip	integration with voip systems

Media type

Type	Description
link	link url
iframe	url which should be shown in an iframe
img	image url
video	video (youtube, vimeo, embedded video)
file	url or base64 file
qrcode	url to qr code image file
smart_document_access	SDA Document

info

If Media Type is video, the media field contains embed url or direct link.

If Media Type is file, the media field may contain an url or base64 content in the following format:

data:application/pdf;base64,JVBERi0xLjQNJe......

Field type

FieldType can have the following values:

Type	Description
TextFieldType	is a plain text
EmailFieldType	is an email address
TelFieldType	is a phone number
LocationFieldType	is an address
DateFieldType	is a date (yyyy:MM:dd) or a date is extracted from text
HourFieldType	represents an hour (HH:mm)
NumFieldType	is a number
BoolFieldType	is true or false
UrlFieldType	is an URL
FullNameFieldType	is a name and surname or a name and surname are extracted from text
CFFieldType	represent a tax code
MultiSelectFieldType	multi select
BirthDateFieldType	it's a date (yyyy:MM:dd) before today
NameFieldType	is a name or a name is extracted from text
SurnameFieldType	is a surname or a surname is extracted from text
PrivacyFieldType	is a privacy consent (true or false)
FileFieldType	is an URI referred to a file
VatFieldType	it's a VAT number
PasswordFieldType	it's a password
DateRangeFieldType	is a range in the form of yyyy:MM:dd - yyyy:MM:dd
DayFieldType	is a day (Monday, Tuesday, ...), depends on form language
HourRangeFieldType	is a range in the form of HH:mm - HH:mm
DayRangeFieldType	is a range of days (e.g. Monday - Friday)
PostalCodeFieldType	is a postal code
BookingDateFieldType	is a date in the form of yyyy:MM:dd after today
BusinessFieldType	is a business name
MeasureFieldType	is a measure value (eg. 1 kg)
CurrencyFieldType	is a currency value (eg. 1 $)
QuantityFieldType	is a quantity value
CatalogFieldType	is a catalog of items
OrderFieldType	is an order number
QRCodeFieldType	value should be retrieved with a qr code reader

info

Algho uses internal validators for these types of fields.

TTS type

Code	Description
NONE	no tts data requested
SINGLE	request single tts data (single sentence) with audio file (in audioUrl of tts object)
MULTIPLE	request multiple tts data (for answers with multiple sentences) with audio file
TEXT_SINGLE	request single tts data (single sentence) without audio file
TEXT_MULTIPLE	request multiple tts data (for answers with multiple sentences) without audio file

Frontend message

Code	Description
FORM_START	indicates that the form begins
FORM_END	indicates that the form is finished

info

Algho notifies these events to the client.

Language codes

Code	Description
it	Italian
en	English
es	Spanish
pt	Portuguese
fr	French
de	German
ro	Romanian
zh	Chinese
ru	Russian

Details

Example

Response with form:

Content-Type: application/json
Body:
{
  "responseType" : "OK",
  "messageCode" : "OK",
  "value" : {
    "conversationId" : 126863,
    "question" : "I'm looking for where to eat",
    "userQuestionText" : "I'm looking for where to eat",
    "questionId" : "206538",
    "solrScore" : 1837.0525,
    "score" : 100.0,
    "baseQA" : false,
    "botId" : "0b76f9173c941284f566a2460c7efeb5",
    "answerList" : [ {
      "answerId" : "314327",
      "answerText" : "<p>Ok</p>",
      "order" : 9999,
      "answerType" : "QA",
      "insertTime" : "2022-09-14 15:26:42",
      "updateTime" : "2022-09-14 15:26:42",
      "ttsAnswerList" : [ {
        "htmlText" : "<p>Ok</p>",
        "plainText" : "Ok",
        "ssmlText" : "<speak> \n <p>Ok</p> \n</speak>"
      } ],
      "gloss" : {"values":[]},
      "conversationItemId" : 382845,
      "questionId" : "206538",
      "enableSuggestions" : "common"
    }, {
      "answerText" : "<p>What do you want to look for?</p>",
      "order" : 1,
      "answerType" : "FORM",
      "options" : [ {
        "optionText" : "Kebab",
        "optionValue" : "Kebab",
        "optionType" : "AdmissibleValue"
      }, {
        "optionText" : "Restaurant",
        "optionValue" : "Restaurant",
        "optionType" : "AdmissibleValue"
      }, {
        "optionText" : "Tavern",
        "optionValue" : "Tavern",
        "optionType" : "AdmissibleValue"
      }, {
        "optionText" : "Avanti",
        "optionValue" : "Avanti",
        "optionType" : "SkipValue"
      }, {
        "optionText" : "Annulla",
        "optionValue" : "Annulla",
        "optionType" : "EndValue"
      } ],
      "ttsAnswerList" : [ {
        "htmlText" : "<p>What do you want to look for?</p>",
        "plainText" : "What do you want to look for?",
        "ssmlText" : "<speak> \n <p>What do you want to look for?</p> \n</speak>"
      } ],
      "conversationItemId" : 382846,
      "field" : {
        "fieldTemplateId" : 23338,
        "fieldType" : {
          "fieldTypeId" : 2,
          "name" : "Text",
          "type" : "TextFieldType",
          "suggestPreviousValues" : true,
          "suggestGlobalSearch" : false,
          "sensible" : false
        },
        "formTemplateId" : 4132,
        "ownerId" : "7d7ea2fc47d182e311ebad6f740174e5",
        "name" : "tipo",
        "questionText" : "<p>What do you want to look for?</p>",
        "order" : 0,
        "required" : false,
        "maxValuesToSelect" : 1,
        "requiredByEtl" : false,
        "deletable" : true,
        "gdprCompliance" : true,
        "hiddenAdmissibleValues" : false,
        "customPicker" : false,
        "avSemanticMatch" : false,
        "selfLearning" : false,
        "entitiesAutofill" : false,
        "disableWriting" : true,
        "showDuringAutofill" : false,
        "showInFullscreen" : false,
        "skipSemanticValidation" : false,
        "admissibleValuesCount" : 0,
        "fieldTypeString" : "TextFieldType"
      },
      "avNextUrl" : ""
    } ],
    "answerType" : "QA",
    "frontEndMessage" : "FORM_START",
    "questionType" : "STANDARD",
    "scoreOrSolrScore" : 100.0
  },
  "serverTime" : "2022-09-14 15:26:53"
}

5 - Engagement

Get the bot engagement messages to show the user after a certain period of inactivity.

Method: POST
Url: /api/engagement/conversation/{conversation_id}?next_engagement={next_engagement}&current_url={current_url}&inputMode={inputMode}&source={source}&callType={callType}&tts={tts}&lipSync={lipSync}&applicationContext={applicationContext}

Request params

Field	Description	Type
conversation_id	conversation id (required)	int
next_engagement	engagement counter (zero based) (required)	int
current_url	current browser url (optional)	string
inputMode	input mode see table	string
source	source type see table	string
callType	call type (standard or sandbox for sandbox mode)	string
tts	tts response type (optional, default: NONE__) see table	string
lipSync	if true, show lip sync data (optional, default: false__)	boolean
applicationContext	application context (used for targeted answers)	string

info

The behavior of tts and lipSync parameters depends on the source field of JSON body.

Details

Example

Request:

POST https://virtualassistant.alghoncloud.com/api/engagement/conversation/104239?next_engagement=0&current_url=https%3A%2F%2Fvirtualassistant.alghoncloud.com%2F%3Fbot%3D0b76f9173c941284f566a2460c7efeb5

Response:

Content-Type: application/json
Body:
{
   "responseType": "OK",
   "messageCode": "OK",
   "serverTime": "2019-11-20 15:37:34",
   "botId": "0b76f9173c941284f566a2460c7efeb5",
   "message": "",
   "value": {
     "answerId": "2325",
     "baseEngagement": true,
     "viewOrder": 0,
     "answerText": "<p>Hey, if you need help, I'm here!<\/p>",
     "enableSuggestions": 1,
     "ttsAnswerList": [
        {
          "ssmlText": "<speak> \n <p>Hey, if you need help, I'm here!<\/p> \n<\/speak>",
          "plainText": "Hey, if you need help, I'm here!",
          "htmlText": "<p>Hey, if you need help, I'm here!<\/p>"
        }
      ],
     "answerType": "QE",
     "options": [
        {
          "optionType": "NextQuestion",
          "optionId": "123762",
          "optionText": "Cosa sai fare?",
          "nextQuestionType": "QA"
        },
        {
          "optionType": "NextQuestion",
          "optionId": "123780",
          "optionText": "Che domande posso farti?",
          "nextQuestionType": "QA"
        }
      ],
     "nextEngagementTime": 20,
     "botId": "0b76f9173c941284f566a2460c7efeb5",
     "label": "15 secondi",
      "oneShot": false
   }
 }

Response structure

Field	Description	Type
answerId	answer id	string
answerText	answer text in html	string
answerType	answer type see table	string
baseEngagement	default bot engagement	boolean
media	media url (optional)	string
mediaType	media type (optional) see table	string
nextEngamentTime	seconds to wait before call engagement from last request (if -1 stop)	int
options	array of options (suggestions) see table	array
ttsAnswerList	array of tts data for the answer (optional) see table	array
label	name of engagement group	string
oneShot	if true, this engagement is shown only once	boolean

info

The field nextEngamentTime return seconds to wait for next engagement. If value is -1 you can stop.

info

After a call you must increment next_engagement counter.

info

After any user request you must reset next_engagement to 0 and timer.

6 - Upvote an answer

Allows you to upvote the answer given by the bot.

Method: POST
Content-Type: application/json
Url: /api/qa/upvote?question_text={question_text}&answer_id={answer_id}&conversation_id={conversation_id}

Request params

Field	Description	Type
question_text	question text	string
answer_id	answer id	int
conversation_id	conversation id	int

Details

Example

Request:

Method: POST
Url: https://virtualassistant.alghoncloud.com/api/qa/upvote?question_text=ciao&answer_id=211426&conversation_id=104239
Content-Type: application/json

Response:

Content-Type: application/json
Body:
{
    "responseType": "OK",
    "messageCode": "OK",
    "serverTime": "2022-02-24 11:10:18"
}

7 - Downvote an answer

Allows you to downvote the answer given by the bot.

Method: POST
Content-Type: application/json
Url: /api/qa/downvote?question_text={question_text}&answer_id={answer_id}&conversation_id={conversation_id}&tts={tts}&lipSync={lipSync}

Request params

Field	Description	Type
question_text	question text	string
answer_id	answer id	int
conversation_id	conversation id	int
tts	tts response type (optional, default: NONE__) see table	string
lipSync	if true, show lip sync data (optional, default: false__)	boolean

Details

Example

Request:

Method: POST
Url: https://virtualassistant.alghoncloud.com/api/qa/downvote?question_text=ciao&answer_id=211426&conversation_id=104239
Content-Type: application/json

Response:

Content-Type: application/json
Body:
{
    "message": "0b76f9173c941284f566a2460c7efeb5",
    "responseType": "OK",
    "messageCode": "OK",
    "value": {
        "conversationId": 104239,
        "solrScore": 0,
        "score": 0,
        "botId": "0b76f9173c941284f566a2460c7efeb5",
        "answerList": [
            {
                "answerText": "Scusa se non sono riuscito a soddisfare la tua richiesta, prova a riformulare la tua domanda.",
                "order": 0,
                "answerType": "SM"
            }
        ],
        "answerType": "SM"
    },
    "conversationId": 104239,
    "serverTime": "2022-02-24 12:02:30"
}