Embed a form in chat

You can embed a form directly within the Inkeep AI assistant chat UI. It can be triggered from a "Contact support" button in the bottom right of the chat or as a dynamic button that appears when the AI assistant is not confident in its answer.

Use this to create a support ticket in your ticketing platform via a custom callback. The history of the conversation can be included.

An example open_form action looks like this:

const formAction: OpenFormAction = {
  type: "open_form",
  formSettings: {
    heading: "Contact Support",
    description: "Please fill out the form below",
    fields: [
      {
        name: "email",
        label: "Email Address",
        inputType: "email",
        isRequired: true,
        placeholder: "Enter your email",
      },
      {
        name: "description",
        label: "Issue Description",
        inputType: "textarea",
        isRequired: true,
        placeholder: "Describe your issue",
      },
      {
        name: "priority",
        label: "Priority Level",
        inputType: "select",
        items: [
          { label: "Low", value: "low" },
          { label: "Medium", value: "medium" },
          { label: "High", value: "high" },
        ],
        isRequired: true,
      },
    ],
    buttons: {
      submit: {
        label: "Submit Ticket",
        onSubmit: async ({ values, conversation }) => {
          // Handle form submission
          await submitTicket(values);
        },
      },
      close: {
        action: "return_to_chat",
      },
    },
    successView: {
      heading: "Ticket Submitted",
      message: "We will get back to you shortly",
      doneButton: {
        label: "Back to Chat",
        action: "return_to_chat",
      },
    },
  },
};

FormSettings Reference

The FormSettings interface provides a comprehensive way to configure forms in your chat interface, through the open_form action type. Here's a detailed breakdown of all available options:

Basic Properties

Property	Type	Required	Description
heading	string	No	The form's title displayed at the top
description	string	No	Explanatory text shown below the heading
fields	FormField[]	Yes	Array of form field configurations
buttons	FormButtons	Yes	Configuration for form action buttons
successView	SuccessView	Yes	Configuration for the success confirmation page

Field Types

Forms support various field types through the FormField union type:

Base 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	Help text shown below the field

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);
      });
    })
  );
}

Include Chat Session Field

Special field type to include chat history:

{
  _type: 'include_chat_session',
  label?: string, // Defaults to "Include chat history"
  defaultValue?: boolean,
  isHidden?: boolean
}

Button Configuration

The buttons property requires configuration for submit and optional close buttons:

{
  buttons: {
    submit: {
      label?: string, // Optional custom label
      onSubmit: async ({ values, conversation }) => {
        // Handle form submission
        // values: Record<string, any> - form field values
        // conversation: ConversationResponse | null
      }
    },
    close?: {
      action: 'return_to_chat' | 'close_modal'
    }
  }
}

Success View Configuration

The successView property configures what's shown after successful submission:

{
  successView: {
    heading: string,    // Success message heading
    message: string,    // Detailed success message
    doneButton: {
      label: string,    // Button text
      icon?: InkeepCustomIcon,  // Optional icon
      action: 'return_to_chat' | 'close_modal'
    }
  }
}

Complete Example

Here's a comprehensive example showing all available configurations:

const formSettings: FormSettings = {
  heading: "Submit Support Request",
  description: "Please provide details about your issue",
  fields: [
    {
      name: "name",
      label: "Full Name",
      inputType: "text",
      isRequired: true,
      placeholder: "John Doe",
      description: "Enter your full name as it appears on your account",
    },
    {
      name: "email",
      label: "Email Address",
      inputType: "email",
      isRequired: true,
      placeholder: "john@example.com",
    },
    {
      name: "priority",
      label: "Priority Level",
      inputType: "select",
      isRequired: true,
      items: [
        { label: "Low", value: "low" },
        { label: "Medium", value: "medium" },
        { label: "High", value: "high" },
      ],
      description: "Select the urgency of your request",
    },
    {
      name: "description",
      label: "Issue Description",
      inputType: "textarea",
      isRequired: true,
      placeholder: "Please describe your issue in detail...",
    },
    {
      name: "terms",
      label: "I agree to the terms of service",
      inputType: "checkbox",
      isRequired: true,
    },
    {
      name: "attachments",
      label: "Attachments",
      inputType: "file",
      description: "Attach any relevant screenshots or files",
    },
    {
      _type: "include_chat_session",
      label: "Include our conversation history",
      defaultValue: true,
    },
  ],
  buttons: {
    submit: {
      label: "Submit Request",
      onSubmit: async ({ values, conversation }) => {
        try {
          // Handle file conversion if needed
          if (values.attachments) {
            values.attachments = await convertFilesToBase64(values.attachments);
          }
 
          // Submit the form data
          await submitSupportRequest({
            ...values,
            chat_history: conversation?.messages,
          });
        } catch (error) {
          throw new Error("Failed to submit support request");
        }
      },
    },
    close: {
      action: "return_to_chat",
    },
  },
  successView: {
    heading: "Request Submitted Successfully",
    message:
      "We have received your support request and will respond within 24 hours.",
    doneButton: {
      label: "Return to Chat",
      icon: { builtIn: "FaArrowLeft" },
      action: "return_to_chat",
    },
  },
};

Embed a form in chat

On this page