Forms in Cliq
Forms in Cliq are used to collect numerous responses or inputs from a user in one go. It’s an alternative to the conversational input for a more structured data. A form can be invoked as a response for the following actions:
- Executing a command
- Sending message to a bot
- Calling a bot's menu action
- Mentioning a bot
- Performing an action on a message - message action
- Clicking a button
The Form Object
A form is a collection of the following attributes shown below. All mandatory attributes are indicated with a *
Attribute | Data Type | Description |
title* | string | The form's title or heading |
hint | string | Describe the form's purpose |
action* | object (cancel: Optional) | The function to be invoked. Define the function invocation flow based on the form action ( submit/ cancel) |
trigger_on_cancel | boolean | Define the form's cancel action with this boolean. |
inputs* | list | List of input fields the form carries |
name* | string(50) | A unique identifier for the form. On form submission, the value provided for this attribute will be available in the form function. |
button_label | string | Button names to be embedded in the form. Default value if no value is specified: Submit |
version | integer | Version ID of the form object. The current version is 1. |
Form Input Fields
A form in Cliq can have a variety of fields categorized primarily on the input method. The input methods are primarily categorised into text and dropdown. The field types are listed below:
Note: You can add a maximum of 25 form input fields.
- Single - line text
- Multi-line text
- Dropdown: Developer defined
- Dropdown: Cliq defined (based on Native select options)
- Pre-filled input
Each form input field has its structure to follow; however, there are a few attributes common across all fields. They are:
Attribute | Type | Description |
type* | string | The type of input field |
name* | string(50) | Unique identifier for the form field. On user action, the value provided for this key will be available in the function associated with the form. |
hint | string | A tip or description briefing the field's purpose |
label* | string(50) | Display name of the field shown to the user |
placeholder* | string | A dummy field value shown to the user on displaying the form |
mandatory | boolean | Categorize your form field as mandatory or optional with this key |
value | string | A default value allocated for the field. The value provided for this field will be displayed when the form is invoked. |
Form Return Types
A form on submit can return the following as a response:
- Error as a response
- Message or Card as a response (similar to return types for commands, message actions and button functions)
Form Error Handling
The form's error object allows you to throw an error message when instantly when a user adds an input that is not intended. Form error messages can be handled for the entire form or for individual fields as well. Take a look at the form error object syntax:
Form Error Object Syntax
{
"type": "form_error",
"text": "$error_text", //Error shown for the entire form on submit
"inputs" : { // Error shown for respective field inputs
"name" : "error_message",
"name" : "error_message"
}
}
Form action on submission or on change
A form collects responses from the user and invokes a function associated with it. Refer this help guide on form functions to learn more about the form action and function invocation. A form function will carry the following arguments:
Attribute | Type | Description |
user | map | Details of the user who is submitting the form |
chat | map | Details of the chat in which the form is invoked |
form | list | Form input data submitted by the user |
message | map | Details of the message for which the form is invoked along with ack_key, time, text, id, type, triggered_by and content |