Forms

Forms is a feature integrated into AI chatbot that allows you to collect structured information from your users. When attached to bot responses, these forms allow end-users to input data into predefined fields, such as email, phone number, name, and more. This functionality not only enhances the efficiency of the interaction but also ensures that the information gathered is organized and specific. This page outlines the process for integrating forms into your app and it focuses on creating and managing custom responses with forms, detecting form-type messages, and handling user input.

Creating custom responses with forms

Using Platform API, you can create a custom response containing from fields that can be attached to bot messages. The request body should include the form structure and fields.

HTTP request

POST https://api-{application_id}.sendbird.com/v3/custom_responses

Request body example

{
  "forms": [
    {
      "key": "personal_info",
      "fields": [
        {
          "key": "company_name",
          "title": "Company Name",
          "input_type": "text",
          "required": true,
          "regex": "REGEX",
          "placeholder": "Enter company name"
        },
        {
          "key": "email",
          "title": "Email",
          "input_type": "email",
          "required": true,
          "regex": "REGEX",
          "placeholder": "Enter email"
        }
      ],
      "messages_after_submission": [
        "Thanks for the submission!",
        "What would you like to do next?"
      ]
    }
  ]
}

Connecting custom response and bot

Using Platform API, you can associate a custom response with a specific bot using this API call. The custom_response_ids array should include the ID(s) of the custom responses created in step 1.

HTTP request

PUT https://api-{application_id}.sendbird.com/v3/bots/{bot_id}

Request body example

{
  "ai": {
    "backend": "",
    "model": "",
    ...
    "custom_response_ids": [1] // ID received from creating custom response above.
  }
}

Handling forms

This section guides on how to detect form type messages, save and validate user input, and submit forms.

Detect form type message

You can check if a message contains forms.

AndroidiOSJavaScript

val BaseMessage.isFormTypeMessage: Boolean
    get() = this.forms.isNotEmpty()

Saving user input

You can update the form field's temporary answer as the user types.

AndroidiOSJavaScript

// Using the TextWatcher of EditText, you can update the FormField.temporaryAnswer as follows.
editText.addTextChangedListener(
    object : TextWatcher {
        ...
        override fun onTextChanged(s: CharSequence, start: Int, before: Int, count: Int) {
            formField.temporaryAnswer = Answer(formField.key, s.toString())
        }
    }
)

Validating user input

You can validate the form field's input and update the UI accordingly.

AndroidiOSJavaScript

editText.addTextChangedListener(
    object : TextWatcher {
        ...
        override fun onTextChanged(s: CharSequence, start: Int, before: Int, count: Int) {
            formField.temporaryAnswer = Answer(formField.key, s.toString())
            if (formField.isSubmittable) {
                // Draw your own UI for valid form field.
            } else {
                // Draw your own UI for invalid form field.
            }
        }
    }
)

Submitting a form

You can submit form data to the server using the submitForm() function. The Chat SDK sends all non-empty formField.temporaryAnswer data to the server. It involves handling possible errors, such as invalid form fields, and updating the message UI upon successful submission.

AndroidiOSJavaScript

// submits form
message.submitForm(form) { e ->
    if (e != null) {
        // handle error
    }
}

// The submitted form is updated through a message update event.
SendbirdChat.addChannelHandler(
    "IDENTIFIER", 
    object : GroupChannelHandler() {
        ...
        override fun onMessageUpdated(channel: BaseChannel, message: BaseMessage) {
            message.forms.find { it.formKey == "TARGET_FORM_KEY" }?.isSubmitted // should be true
            // Update message UI to submitted form.
        }
    }
)

Enable form type message in UIKit

You can enable the form type message feature in UIKit by following the code below.

AndroidiOSJavaScript

// BaseApplication.kt
UIKitConfig.groupChannelConfig.enableFormTypeMessage = true

On this page

Creating custom responses with forms Connecting custom response and bot Handling forms

Detect form type message Saving user input Validating user input Submitting a form

Enable form type message in UIKit