Customization guides

Embedded Support Forms

Use our AI annotations to intelligently show a contact support button and integrate with your support system.

Scenario

If the bot was not able to answer a user's question, you can optionally show a contact support button which can be configured to either open a customizable form or call a custom callback function. The form can be configured to collect whatever information you would like and you may optionally include information about the user's chat session which can then be turned into a support ticket. The callback function can be used to initiate a live chat.

Example

import { type InkeepAIChatSettings, type FormConfig } from "@inkeep/uikit";
 
const supportFormConfig: FormConfig = {
  heading: "Contact support",
  fields: [
    {
      type: "STANDARD_FIELD",
      label: "Name",
      name: "first_name",
      inputType: "TEXT",
    },
    {
      type: "STANDARD_FIELD",
      label: "Email",
      name: "email",
      inputType: "EMAIL",
      required: true,
    },
    {
      type: "INCLUDE_CHAT_SESSION",
      defaultValue: true,
    },
    {
      type: "STANDARD_FIELD",
      label: "Additional details",
      name: "additional_details",
      inputType: "TEXTAREA",
    },
    {
      type: 'STANDARD_FIELD',
      label: 'Category',
      name: 'category',
      inputType: 'SELECT',
      selectOptions: [
        { label: 'Bug', value: 'BUG' },
        { label: 'Feature idea', value: 'FEATURE' },
        { label: 'Account access', value: 'ACCOUNT' },
      ],
    },
  ],
  submitCallback: (values) => {
    // replace with your own api call to create a support ticket
    return new Promise((resolve) => {
      setTimeout(() => {
        resolve({ success: true });
      }, 2000);
    });
  },
};
 
const inkeepAIChatSettings: InkeepAIChatSettings = {
  //... rest of inkeepAIChatSettings
  includeAIAnnotations: {
    shouldEscalateToSupport: true,
  },
  aiAnnotationPolicies: {
    shouldEscalateToSupport: [
      {
        threshold: "STANDARD", // "STRICT" or "STANDARD"
        action: {
          type: "SHOW_SUPPORT_BUTTON",
          label: "Contact Support",
          icon: { builtIn: "LuUsers" },
          action: {
            type: "OPEN_FORM",
            formConfig: supportFormConfig,
          },
        },
      },
    ],
  },
};

IncludeAIAnnotations

This is currently an enterprise preview feature.

PropertyTypeDescription
shouldEscalateToSupportbooleanWhether or not to include the shouldEscalateToSupport annotation.

AIAnnotationPolicies

Be sure to include the corresponding property in includeAIAnnotations.

PropertyTypeDescription
shouldEscalateToSupportShouldEscalateToSupportPolicy[]Policies for shouldEscalateToSupport.

ShouldEscalateToSupportPolicy

PropertyTypeDescription
threshold"STANDARD""STRICT"
actionShowEscalateToSupportButtonActionAction to take when support escalation threshold is met.

ShowEscalateToSupportButtonAction

PropertyTypeDescription
type"SHOW_SUPPORT_BUTTON"Type of action.
labelstringButton label.
iconCustomIconIcon that goes next to the button label. See here for details.
actionOpenFormActionInvokeCallbackAction

OpenFormAction

PropertyTypeDescription
type"OPEN_FORM"Type of action.
formConfigFormConfigCustom form configuration. See here for details.

InvokeCallbackAction

PropertyTypeDescription
type"INVOKE_CALLBACK"Type of action.
callback(args: InvokeCallbackArgs) => voidCallback to be invoked when the button is clicked. See here for details.
shouldCloseModalbooleanDetermines whether the chat modal should close when the callback is invoked. Default is false.

InvokeCallbackArgs

PropertyTypeDescription
chatSessionIdstringId for the chat session.
messagesMessage[]Messages from the chat session.

FormConfig

PropertyTypeDescription
headingstringHeading of the form.
descriptionstringDescription of the form.
fields(FormField | IncludeChatSessionField)[]Required. Fields to include in the form. See here for details.
submitButtonLabelstringLabel for the form submit button. Default is Submit.
submitCallback(values: SubmitCallbackArgs) => Promise<{ success: boolean }>Required. Function that is called when the form is submitted. See here for details.
successConfirmationPageSuccessConfirmationPagePropsConfiguration for the confirmation page that is displayed when the form has successfully been submitted. See here for details.
closeFormActionBackToChatFormActionModalCloseFormAction

FormField

PropertyTypeDescription
type"STANDARD_FIELD"Required.
namestringRequired. Name of the input, this will be the key of the input's value in the form data, therefore it must be unique.
labelstringRequired. Label for the input.
inputTypeCHECKBOXEMAIL
placeholderstringPlaceholder text for the input.
requiredbooleanWhether or not the field is required. Default is false.
defaultValuestringboolean
isHiddenbooleanWhether or not to show the field in the form. Default is false.
selectOptionsSelectOption[]Options for the SELECT field dropdown. Required if inputType is SELECT. See here for details.

SelectOption

PropertyTypeDescription
labelstringLabel of the option in the dropdown (visible to the user).
valuestringValue of the dropdown option, this is what is returned in the submitCallback formDetails. Should be unique amongst the selectOptions.

IncludeChatSessionField

If this field is included in the form and the value is true, the arguments supplied to submitCallback will include the chat session information. If it is not included or the value is false, chatSession will be null. The name of this field in the form values will be include_chat_session. If you would like to automatically include the chat session information without showing this field in the form, set isHidden to true and defaultValue to true. If there is no chatSession data (because the user didn't ask any questions yet), this field will be automatically hidden and set to required: false.

PropertyTypeDescription
type"INCLUDE_CHAT_SESSION"Required.
labelstringLabel for the checkbox. Default is Include chat history.
requiredbooleanWhether or not the field is required. Default is false.
defaultValuebooleanDefault value to populate the input with. Default is false.
isHiddenbooleanWhether or not to show the field in the form. Default is false.

SubmitCallback

The submitCallback is called when the form is submitted. It will be called with the following arguments and should return a Promise that resolves to { success: boolean }.

PropertyTypeDescription
formDetailsFieldValuesAn object containing the form values where the key is the input name and the value is the input value.
chatSessionChatSessionnull
clientClientDetails about the client. See here for details.

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

ChatSession

PropertyTypeDescription
chatSessionIdstringId for the chat session.
messagesMessage[]Messages from the chat session.

Client

PropertyTypeDescription
currentUrlstringURL that the user was on when the form was submitted.

SuccessConfirmationPageProps

PropertyTypeDescription
headingstringThe success message heading. Default is Thank you!.
messagestringThe success message. You can include links using markdown. Default is Your form has been submitted successfully..
successConfirmationButtonSuccessConfirmationButtonConfiguration for the button on the success confirmation page. If not included, the button will not be displayed.

SuccessConfirmationButton

PropertyTypeDescription
labelstringThe button label.
iconCustomIconThe icon to the left of the button label. See here for details.
closeFormActionBackToChatFormActionModalCloseFormAction

BackToChatFormAction

PropertyTypeDescription
type"BACK_TO_CHAT"Will navigate back to the AI Chat view.

ModalCloseFormAction

PropertyTypeDescription
type"CLOSE_MODAL"Will close the modal (not applicable for the EmbeddedChat).