Form

The form settings control the behavior, layout, and functionality of the Intelligent Form widget. The form is structured in two sections: primary and secondary, with additional configuration for success view and submission handling.

Configuration Structure

This is the structure of the IntelligentFormSettings object. We'll go through each item in detail below.

interface IntelligentFormSettings {
  aiAssistantName?: string;
  primary: PrimarySection;
  secondary: SecondarySection;
  successView: IntelligentFormSuccessView;
  buttons: IntelligentFormButtons;
}

Assistant Name

The aiAssistantName property is optional and is the name that is displayed in the form.

const formSettings = {
  aiAssistantName: "Support Agent",
};

Primary Section

The primary section contains the initial form fields that are always displayed.

interface PrimarySection {
  fields: IntelligentFormField[];
  description?: string;
}

Property	Type	Required	Description
`fields`	`IntelligentFormField[]`	Yes	Array of form fields to display initially
`description`	`string`	No	Optional description text shown above the fields

Example Primary Section

{
  primary: {
    fields: [
      {
        label: 'Name',
        name: 'name',
        inputType: 'text',
        isRequired: true,
      },
      {
        label: 'Email',
        name: 'email',
        inputType: 'email',
        isRequired: true,
      },
      {
        label: 'How can we help?',
        name: 'additionalDetails',
        inputType: 'textarea',
        placeholder: 'Please provide any additional details that may be helpful.',
      },
    ],
  }
}

Secondary Section

The secondary section contains additional fields that can be conditionally shown, often used for AI-enhanced form fields.

interface SecondarySection {
  fields: IntelligentFormField[];
  description?:
    | string
    | {
        default: string;
        confident: string;
      };
}

Property	Type	Required	Description
`fields`	`IntelligentFormField[]`	Yes	Array of form fields to display in the secondary section
`description`	`string \| DescriptionObject`	No	Description text or object with confidence-based messages

Example Secondary Section

{
  secondary: {
    description: {
      default: 'To finish submitting a support ticket, confirm the fields below and click Submit.',
      confident: 'Understood. Please confirm the below information:',
    },
    fields: [
      {
        label: 'Subject line',
        name: 'subject',
        inputType: 'text',
        isRequired: true,
        description: 'Overview of the issue',
        defaultValue: 'General Inquiry',
      },
      {
        label: 'Priority',
        name: 'priority',
        inputType: 'select',
        isRequired: true,
        items: [
          { label: 'Urgent', value: 'URGENT' },
          { label: 'High', value: 'HIGH' },
          { label: 'Medium', value: 'MEDIUM' },
          { label: 'Low', value: 'LOW' },
        ],
        placeholder: 'Select a priority',
      },
    ],
  }
}

Form Fields

Form fields can be of different types, each with its own specific properties.

Field Types

Forms support various field types through the IntelligentFormField union type:

Common Field Properties

All field types inherit these base properties:

Property	Type	Required	Description
`name`	`string`	Yes	Unique identifier for the field
`label`	`string`	Yes	Display label for the field
`isRequired`	`boolean`	No	Whether the field is required
`isHidden`	`boolean`	No	Whether to hide the field
`description`	`string`	No	Helper text shown below the field
`shouldPrefillWithAi`	`boolean`	No	Determines if the field gets pre-generated by AI

Text Field

{
  name: 'name',
  label: 'Full Name',
  inputType: 'text',
  defaultValue?: string,
  placeholder?: string
}

Email Field

{
  name: 'email',
  label: 'Email Address',
  inputType: 'email',
  defaultValue?: string,
  placeholder?: string
}

Textarea Field

{
  name: 'description',
  label: 'Description',
  inputType: 'textarea',
  defaultValue?: string,
  placeholder?: string
}

Checkbox Field

{
  name: 'subscribe',
  label: 'Subscribe to newsletter',
  inputType: 'checkbox',
  defaultValue?: boolean
}

Select Field

{
  name: 'category',
  label: 'Category',
  inputType: 'select',
  items: [
    { label: 'Option 1', value: 'opt1' },
    { label: 'Option 2', value: 'opt2' }
  ],
  defaultValue?: string,
  placeholder?: string
}

File Field

{
  name: 'attachment',
  label: 'Attach File',
  inputType: 'file'
}

When using a file field in your form, you may need to convert the files to Base64 before sending to your backend or an external API, this can be done by using the following snippet.

function convertFilesToBase64(files: FileList) {
  const filesArray = Array.from(files);
  return Promise.all(
    filesArray.map((file) => {
      return new Promise((resolve, reject) => {
        const reader = new FileReader();
        reader.onload = (event) => {
          const result = (event.target as FileReader).result;
          const base64Data = result.replace(/^data:.+;base64,/, "");
          resolve({
            data: base64Data,
            fileName: file.name,
            mimeType: file.type,
          });
        };
        reader.onerror = (error) => reject(error);
        reader.readAsDataURL(file);
      });
    })
  );
}

Success View

Configuration for the view shown after successful form submission.

interface IntelligentFormSuccessView {
  heading: string;
  message: string;
  icon?: InkeepCustomIcon;
}

Property	Type	Required	Description
`heading`	`string`	Yes	Success message heading
`message`	`string`	Yes	Detailed success message
`icon`	`InkeepCustomIcon`	No	Custom icon to display

Example Success View

{
  successView: {
    heading: 'Thank you!',
    message: "We'll be in touch soon",
  }
}

Button Configuration

The buttons property requires configuration for the submit button.

The onSubmit callback is called when the form is submitted. It exposes the form values and additional context.

interface SubmitCallbackArgs {
  values: Record<string, any>;
  conversation: ConversationResponse | null;
}
 
type SubmitCallback = (args: SubmitCallbackArgs) => Promise<void> | void;

{
  buttons: {
    submit: {
      label?: string, // Optional custom label
      onSubmit: async ({ values, conversation }) => {
        // Handle form submission
        // values: Record<string, any> - form field values
        // conversation: ConversationResponse | null
        try {
          // Access form values
          const { name, email, subject, priority } = values;
 
          // Access conversation context if available
          const conversationId = conversation?.id;
 
          // Submit to your API
          await submitToAPI({
            ...values,
            conversationId,
          });
        } catch (error) {
          // Handle submission error
          console.error("Form submission failed:", error);
          throw error; // Re-throw to show error in form
        }
      }
    }
  }
}

Complete Example

const formSettings = {
  primary: {
    fields: [
      {
        label: "Name",
        name: "name",
        inputType: "text",
        isRequired: true,
      },
      {
        label: "Email",
        name: "email",
        inputType: "email",
        isRequired: true,
      },
      {
        label: "How can we help?",
        name: "additionalDetails",
        inputType: "textarea",
        placeholder:
          "Please provide any additional details that may be helpful.",
      },
    ],
  },
  secondary: {
    description: {
      default:
        "To finish submitting a support ticket, confirm the fields below.",
      confident: "Understood. Please confirm the below information:",
    },
    fields: [
      {
        label: "Subject line",
        name: "subject",
        inputType: "text",
        isRequired: true,
        description: "Overview of the issue",
        defaultValue: "General Inquiry",
      },
      {
        label: "Priority",
        name: "priority",
        inputType: "select",
        isRequired: true,
        items: [
          { label: "Urgent", value: "URGENT" },
          { label: "High", value: "HIGH" },
          { label: "Medium", value: "MEDIUM" },
          { label: "Low", value: "LOW" },
        ],
        placeholder: "Select a priority",
      },
      {
        label: "Ticket type",
        name: "ticketType",
        inputType: "select",
        isRequired: true,
        items: [
          { label: "Talk to sales", value: "talk_to_sales" },
          { label: "Issue in production", value: "issue_in_production" },
          { label: "Issue in development", value: "issue_in_development" },
          { label: "Report bug", value: "report_bug" },
          { label: "Onboarding help", value: "onboarding_help" },
          { label: "Account management", value: "account_management" },
          { label: "Feature request", value: "feature_request" },
        ],
        placeholder: "Select a ticket type",
      },
    ],
  },
  successView: {
    heading: "Thank you!",
    message: "We'll be in touch soon",
  },
  buttons: {
    submit: {
      label: "Submit",
      onSubmit: async ({ values, conversation }) => {
        console.log("Form submitted:", {
          values,
          conversationId: conversation?.id,
        });
      },
    },
  },
};

On this page