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 *

AttributeData TypeDescription
title*stringThe form's title or heading
hintstringDescribe 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_cancelbooleanDefine the form's cancel action with this boolean.
inputs*listList 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_labelstringButton names to be embedded in the form. Default value if no value is specified: Submit
versionintegerVersion 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:

AttributeTypeDescription
type*​stringThe 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. 
hintstringA tip or description briefing the field's purpose 
label*string(50)Display name of the field shown to the user
placeholder*stringA dummy field value shown to the user on displaying the form
mandatorybooleanCategorize your form field as mandatory or optional with this key
valuestringA 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: 

AttributeTypeDescription
usermapDetails of the user who is submitting the form
chatmapDetails of the chat in which the form is invoked
formlistForm input data submitted by the user
messagemapDetails of the message for which the form is invoked along with ack_key, time, text, id, type, triggered_by and content