Dynamic Form

In questa sezione

Request

{
  "userQuestion": {
    "userId": "userId",
    "botId": "botId",
    "conversationId": 832764,
    "question_text": "the user question input"
  },
  "intent" : {
    "intentId": 1234,
    "botId": "botId",
    "name": "Intent name",
    "questions": [
      {
        "questionText": "the question text"
      }
    ],
    "answers": [
      {
        "answerText": "The answer text",
        "mediaType": "link",
        "media": "https://wwww.google.com",
        "answerType": "QA",
        "chosen": true
      }
    ]
  },
  "answers": [
      {
      "answerText": "The answer text",
      "mediaType": "link",
      "media": "https://wwww.google.com",
      "answerType": "QA"
    }
  ],
  "previousMessages": [
    {
      "userQuestion": "Hey bot",
      "botMessageText": "Hey user"
    }
  ],
  "metadata": {
    "a": "b"
  },
  "formInstanceId": "2135",
  "formInstanceStatus": "INCOMPLETE",
  "validationResult": "XXXXXX",
  "previousValues": [
    // see description
  ],
  "autofilled": false,
  "skipped": false,
  "interrupted": false
}

Details

User question

Contains the user query, along other informations.

Field	Description	Notes
`userId`	the user id	always present
`botId`	the bot id	always present
`conversationId`	the conversation id	it can be null on first message from the user to the bot
`currentUrl`	the URL from which the message was sent	optional, nullable
`questionId`	the intent ID specified in the message	optional, nullable
`inputType`	the type of input	optional, nullable
`source`	the source of the message	optional, nullable
`applicationContext`	the context of the message	optional, nullable
`wsBasePath`	the base path of the WS	optional, nullable
`question_text`	the user question text	always present

Intent

If the dynamic form was invoked by an intent, this field will be present. The fields are self-explanatory, the other things to know are:

if an intent has more than one answer, the matched one (by Algho responder) will have chosen set as true
the answer type can be:
- QA, meaning a found answer
- QB, meaning a not found answer
- QD, a disambiguation
the media type can be:
- img, meaning the media field will need to contain a link/base64 image
- link, meaning the media field will contain an URL to a web page
- video, the same as the image but for videos

Answers

The answers field will hold the answer found by the responder before calling the WS. See above.

Messages

It will holds the messages in the conversation exchanged by the user with the bot. This will be present only in the first call to the WS starting the form.

Metadata

It will hold a custom json set from a response from the WS. In the first call it will be the wsMetadata set in the answer (both from the intent answer or the quibble). The WS must populate this field accordingly, as it will be null unless set from the WS.

formInstanceId

A unique identifier of the form instance.

formInstanceStatus

The form instance status, it can be:

Value	Description
`INCOMPLETE`	The form is incomplete. This is the starting status.
`SUCCESS`	The form is completed with success.
`FAILED`	The form is failed due to user error.
`INTERNAL_FAIL`	The form is failed due to a WS error.

In the request it will only be INCOMPLETE. The other states will be used in the response.

validationResult

This key, only present in the requests after the first, will hold the validation performed by Algho on the field gave to the user. For example, in the case of date field gave to the user may hold (if found) the normalized value of the date specified by the user. If validation is failed (i.e. no valid date is given from the user) this key will be empty or not in the request.

previousValues

It will hold field history sent in subsequent response (see response description). In the first request it will be null.

autofilled

If the core extracted some values from the previous user question this flag will be true

skipped

If true it means that the user skipped the previous field

interrupted

If true it means that the user clicked on the option to interrupt the form.

The web service can use this information to give one ore more custom messages using the answers in the response and to do internal operation.

In case of no answers in the response nothing will be shown to the user.

Response

{
  "answers": [
      {
      "answerText": "The answer text",
      "mediaType": "link",
      "media": "https://wwww.google.com",
      "answerType": "QA"
    }
  ],
  "formStatus": "INCOMPLETE",
  "formName": "The custom form name",
  "fieldTemplate": {
      // check the description below
  },
  "nextEndpoint": "https://www.google.com",
  "metadata": { /* see the request example */ },
  "values": [
    // optional, see description
  ]
}

Details

answers

It will hold the answers to be shown to the user, see the request details for the format as it's the same.

formInstanceStatus

If not set to INCOMPLETE it will end the form accordingly to the specified status.

formName

If set it will be used in the algho form data for history purpose, otherwise it will be autogenerated.

fieldTemplate

The field shown to the user:

Field	Description	Notes
`fieldType`	The type of the field to be shown to the user	See the table below for the types
`questionText`	The question to be send to the user	Mandatory
`maxValuesToSelect`	The max number of admissible values (if present) to be shown	Optional, default 1
`disableWriting`	If the text input box must be enabled or not	Optional, deafult false
`showInFullscreen`	If the admissible values must be shown in fullscreen	Optional, default false
`skippable`	If the user can skip the field	Required
`interruptable`	If the user can abort the form	Required
`admissibleValues`	Mandatory admissible values for the user, they can be optional - Array of possible values	Optional

Field type description

Key	Description
`TextFieldType`	is a plain text
`EmailFieldType`	is an email address
`NumFieldType`	is a number (only digits allowed)
`AreaCodeFieldType`	is an area code number (eg. +39, +34, +442 etc.)
`TelFieldType`	is a phone number
`LocationFieldType`	is an address
`PostalCodeFieldType`	is a postal code
`DateFieldType`	is a date (yyyy-MM-dd) or a date is extracted from text
`BirthDateFieldType`	is a date in the past (yyyy-MM-dd)
`BookingDateFieldType`	is a date in future, starting from today (yyyy-MM-dd)
`DayFieldType`	is a day (Monday, Tuesday etc.), depends on form language
`HourFieldType`	represents an hour (HH:mm)
`DateHourFieldType`	is both a day and a date (yyyy-MM-dd HH:mm)
`DateRangeFieldType`	is a range of dates (yyyy-MM-dd - yyyy-MM-dd)
`DayRangeFieldType`	is a range of days (Monday - Friday)
`HourRangeFieldType`	is a range of hours (HH:mm - HH:mm)
`BoolFieldType`	is a choice between TRUE of FALSE
`NameFieldType`	is a name or a name is extracted from text
`SurnameFieldType`	is a surname or a surname is extracted from text
`FullNameFieldType`	is a name and surname or a name and surname are extracted from text
`CFFieldType`	is a tax code
`VatFieldType`	is a VAT number
`UrlFieldType`	is an URL
`FileFieldType`	is the URL of a file uploaded by the user
`AudioFieldType`	is the URL of an audio recorded by the user
`QRCodeFieldType`	is the content of a QR code scanned by the user
`SPIDFieldType`	are the content of a successful SPID login
`PasswordFieldType`	represents a password, it will be hashed one-way and is not reversible
`PrivacyFieldType`	is a BoolFieldType dedicated to the privacy consent (eg. service, marketing, profiling, etc.)
`BusinessFieldType`	is the name of a business, or what is extracted as the name of a business
`CatalogFieldType`
`CurrencyFieldType`	rapresents a currency (eg. €, $, £, ¥)
`MeasureFieldType`	is a measurable normalized quantity (eg. "5 kg", "15 mA")
`QuantityFieldType`	is a non-normalized quantity (eg. "5 grams")
`OrderFieldType`	is the ID of an existing order

Admissible value will have two keys, "name" and "alias": "name" field will be the name of the valid value (mandatory field) displayed in the interface, while the "alias" field will be the alias of the displayed name (not mandatory). The "alias" field can contain several synonyms of the name, separated by a comma.

nextEndpoint and metadata

Will hold the next endpoint to call if the form it's not over. The metadata if present will be set for the next calls to the WS.

values

It will save the values in the field history in Algho. Values saved will be in the same format in subsequent requests

Field	Description	Notes
`fieldType`	The type of the field	See the table above
`value`	The value saved	Mandatory
`name`	The name of the field to be saved	Optional, default random
`externalId`	The external id	Optional, default null
`admissibleValues`	The admissible values	Optional, see above

In questa sezione​

Request​

Details​

User question​

Intent​

Answers​

Messages​

Metadata​

formInstanceId​

formInstanceStatus​

validationResult​

previousValues​

autofilled​

skipped​

interrupted​

Response​

Details​

answers​

formInstanceStatus​

formName​

fieldTemplate​

Field type description​

nextEndpoint and metadata​

values​

In questa sezione

Request

Details

User question

Intent

Answers

Messages

Metadata

formInstanceId

formInstanceStatus

validationResult

previousValues

autofilled

skipped

interrupted

Response

Details

answers

formInstanceStatus

formName

fieldTemplate

Field type description

nextEndpoint and metadata

values