External Engine

In questa sezione

1

Request

Vai alla sezione→

2

Response

Vai alla sezione→

3

WEBHOOK

Vai alla sezione→

---

Request

{
  "userQuestion": {
    "userId": "userId",
    "botId": "botId",
    "conversationId": null,
    "currentUrl": "www.google.com",
    "questionId": -1,
    "command": null,
    "callType": "standard",
    "inputMode": "keyboard",
    "source": "text_landscape",
    "sourceType": "web",
    "disableFieldHistory": false,
    "applicationContext": null,
    "wsBasePath": null,
    "question_text": "Ciao"
  },
  "previousStepResults": [
    {
      "intentId": 123,
      "intentName": "Ciao",
      "questionText": "Ciao",
      "answer": {
        "answerText": "Ciao a te",
        "answerId": 1234
      },
      "externalId": "id"
    }
  ],
  "history": [
    {
      "userQuestion": "Hey bot",
      "botMessageText": "Hey user"
    }
  ],
  "uuid": "b91f097b-f5f7-4825-be1d-1112a4f2c3ca"
}

Details

UserQuestion

userQuestion is the question from the user - will always be present

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
uuid	the UUID for webhook response (optional). More details in the Webhook section below.	string

History

history is a list of objects containing the messages of the conversation

PreviousStepResults

previousStepResults are the results from the previous pipeline step (may be null or empty)

Field	Description	Type	Optional
intentId	the intent id	long	yes
intentName	the intent name	string	yes
questionText	the question text	string	no
answer	contains the answer text and the optional answer id	object	-
externalId	the stored external id for the intent	string	yes

Response

{
  "interruptPipeline": true,
  "results": [
    {
      "intentId": 123,
      "intentName": "Ciao",
      "questionText": "Ciao",
      "answer": {
        "answerText": "Ciao a te",
        "answerId": 1234
      },
      "externalId": "id"
    }
  ],
  "answers": [
    {
      "answerId": "106049",
      "answerText": "Hi",
      "answerType": "QA"
    }
  ]
}

Details

• interruptPipeline will interrupt the pipeline if set as true. If any answers are present they will be prompted to the user
• results will be used in case of uninterrupted pipeline, passing them to the next step
• answers will be set as answers to the user. It's advisable to use answers with interruptPipeline set as true or results with interruptPipeline set as false.

The last answer of the answers list may start a dynamic form (refer to its documentation for more details) using a nextQuestion:

{
  "answerText": "Answer starting a dynamic form",
  "answerType": "QA",
  "nextQuestions": [
    {
      "label": "Dynamic form name",
      "nextQuestionType": "DYNAMIC_FORM",
      "url": "https://www.google.it",
      "questionText": "Dynamic form name"
    }
  ]
}

Answers

Field	Description	Type
answerText	answer text in html (always mandatory)	string
answerId	answer id (optional)	string
media	media url (optional)	string
mediaType	media type (optional) see table	string
answerType	answer type see table	string
payload	Custom command (used for browser automation, voip commands)	string
first *	if this is the first answer (mandatory in asynchronous mode). Check the Webhook section below.	boolean
last *	if this is the last answer (mandatory in asynchronous mode). Check the Webhook section below.	boolean
index *	the order of this answer (0-based) (mandatory in asynchronous mode). Check the Webhook section below.	integer

AnswerType ENUM

Type	Name	Description
QA	Answer	answer found in the knowledge base
QB	Quibble	circumstance answers for questions to which the chatbot has no answer

MediaType ENUM

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

WEBHOOK

If the request payload contains the uuid field, you MAY provide paragraphs asynchronously via webhooks.

In order to do so, respond to the request with a response having this body:

{
  "asyncResponse": true
}

At this point, the uuid received in the request will be enabled to receveing asynchronously answers.

For each paragraph, call the following endpoint in POST:

https://composer.alghoncloud.com/api/conversate_item/webhook/{uuid}

where the uuid is the string received in the request.

Any request with a wrong / unrecognized uuid will be dropped silently.

The body contains a single answer (with the same structure documented above), with the addition of 3 new fields:

• first, boolean, which indicates that this is the first answer
• last, boolean, which indicates that this is the last answer
• index, integer, which indicates the order of the answer itself (0-based)

Those 3 new fields are mandatory and MUST be present in the response payload.

If one of them is missing then the API will respond with status code 4xx.

On the user interface, a loading spinner will be displayed until the response where "last":true is received.

EXAMPLES

    {
      "answerText": "<p>First answer</p>",
      "answerType": "QA",
      "first": true,
      "last": false,
      "index": 0
    }

{
  "answerText": "<p>Second answer</p>",
  "answerType": "QA",
  "first": false,
  "last": false,
  "index": 1
}

{
  "answerText": "<p>Last answer</p>",
  "answerType": "QA",
  "mediaType": "img",
  "media": "https://picsum.photos/200/300",
  "first": false,
  "last": true,
  "index": 2
}

It is also possible to call a dynamic form on the answer with "last":true. Refer to the relevant documentation.

{
  "answerText": "<p>Starting form.</p>",
  "answerType": "QA",
  "nextQuestions": [{
        "nextQuestionType": "DYNAMIC_FORM",
        "url": "http://my.dinamic.form/endpoint"
    }],
  "first": true,
  "last": true,
  "index": 0
}

NOTES:

• the uuid will NOT be available immediately;
• the uuid will be available a few milliseconds after the external engine has responded to Algho;
• the external engine must take care of the order in which the paragraphs are presented to the user (via the index field). Before presenting them to the user, Algho will apply text-to-speech, lip-sync, ect.
• the uuid will remain valid for 2 minutes after the last successful request received (each successful request refreshes the decay timer to 2 minutes);
• the uuid will be terminated as soon as a request with an answer containing "last":true is received and further requests for that uuid will be dropped.