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.

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