Customization guides

Workflows

Workflows

Workflows allow you to create application-specific flows that map to common scenarios your users may face. These often map to specific tasks in your onboarding or user journey.

A workflow supports:

  • A custom initial message
  • Specifying clarifying questions or information the bot should ask for
  • Custom attachment types that can invoke forms, modals, or API calls within your front-end application to gather user-specific information

Example

example.ts
import { type Workflow } from "@inkeep/uikit";
import { type InkeepAIChatSettings } from "@inkeep/uikit";
 
const integrateWithMyAppWorkflow: Workflow = {
  id: "ikp_integrate_with_my_app",
  displayName: "Help me integrate with my app",
  goals: [
    "Identify the platform that the user is looking to add Inkeep on. Can be a website-based platform or docs platform, Slack/Discord bots, or via API",
    "Give instructions for how to add the bot to that platform."
  ],
  botPersona: "You are an expert solutions engineer",
  informationToCollect: [
    {
      description: "Platform they are integrating Inkeep to",
      required: true,
    },
  ],
  guidance: [
    "If not clear from the user's message, ask clarifying questions to understand the underlying platform (e.g. Docusaurus vs Slack vs ReadMe, etc.).", 
    "If the platform is not detailed in our quickstarts, then ask whether it's a React or JavaScript based platform so you can give the right guidance based on that.",
  ],
  initialReplyMessage:
    "Happy to help. \n Where are you looking to add Inkeep?",
};
 
//...rest of your settings
const aiChatSettings: InkeepAIChatSettings = {
  //... rest of aiChatSettings
  workflows: [integrateWithMyAppWorkflow]
};

Workflow

PropertyTypeDescription
idstringRequired. Id of the workflow.
displayNamestringRequired. Label of workflow in the UI.
goalsstring[]Required. Goals for the workflow, not visible to the user.
informationToCollectWorkflowInformationToCollect[]Required. Information to collect from the user. Learn more.
botPersonastringThe persona of the bot useful for defining the character, tone, and interaction style the bot will adopt when communicating with users.
contextstring[]Additional context about this workflow for the LLM, not visible to the user.
guidancestring[]Additional guidance for the LLM, not visible to the user.
initialReplyMessagestringRequired. The reply message from the bot after the user selects a workflow.
supportedInputs(WorkflowModalSingleInput | WorkflowFunctionalMultiInput)[]Configuration for the workflow inputs. Learn more.

WorkflowInformationToCollect

PropertyTypeDescription
descriptionstringRequired. Description of the information to be collected from the user in order to assist them through the workflow.
requiredbooleanRequired. Whether or not this information is required.

Attachments - Built In Modal

example.ts
import { type Workflow, type WorkflowModalSingleInput } from "@inkeep/uikit";
 
const exampleWorkflow: Workflow = {
  id: "example_workflow",
  displayName: "Share Error Log",
  goals: [
    "Collect error log information from the user",
    "Provide guidance based on the error log content"
  ],
  botPersona: "You are a helpful technical support assistant",
  informationToCollect: [
    {
      description: "Error log details",
      required: true,
    },
  ],
  initialReplyMessage: "I'd be happy to help you with your error. Please share your error log using the button below.",
  supportedInputs: [{
    id: "error_log_input",
    type: "MODAL",
    displayName: "Share Error Log",
    contentType: {
      type: "CODE",
      contentInputLabel: "Error Log",
      language: "plaintext",
    },
    workflowModalProps: {
      titleInputLabel: "Error Description",
      modalHelpText: "Please paste your error log and provide a brief description of when this error occurred.",
    },
  } as WorkflowModalSingleInput],
};

WorkflowModalSingleInput

This input type will open a built-in modal with a form based on the configuration below to collect the user's information.

PropertyTypeDescription
idstringRequired. Id of the input.
type"MODAL"Required.
displayNamestringRequired. Button label in the UI that opens the modal.
contentTypeWorkflowCodeContentTypeWorkflowTextContentType
workflowModalPropsWorkflowModalPropsAdditional modal configuration. Learn more.

WorkflowModalProps

PropertyTypeDescription
titleInputLabelstringLabel for the title input. Defaults to "Title".
modalHelpTextstringHelp text shown in the modal.
modalHelpElementReactElementHelp element shown in the modal.

WorkflowCodeContentType

PropertyTypeDescription
type"CODE"Required.
contentInputLabelstringRequired. Label for the content input, also provided to the LLM when chat is submitted.
attachmentIconCustomIconIcon next to the title in the attachment item. Learn more.
languagestringCode language.

WorkflowTextContentType

PropertyTypeDescription
type"TEXT"Required.
contentInputLabelstringRequired. Label for the content input, also provided to the LLM when chat is submitted.
attachmentIconCustomIconIcon next to the title in the attachment item. Learn more.

MessageAttachment

PropertyTypeDescription
contentTypeWorkflowCodeContentTypeWorkflowTextContentType
titlestringRequired. Attachment title.
contentstringRequired. Attachment content.
idstringRequired. Attachment id.
contextstring[]Additional attachment context.

Attachments - In-app callback

example.ts
import { type Workflow, type WorkflowFunctionalMultiInput, type MessageAttachment } from "@inkeep/uikit";
 
const troubleshootErrorWorkflow: Workflow = {
  id: "troubleshoot_error_workflow",
  displayName: "Troubleshoot Error",
  goals: ["Collect error information", "Provide initial troubleshooting steps"],
  botPersona: "You are an expert technical support engineer",
  informationToCollect: [{ description: "Error details", required: true }],
  initialReplyMessage: "I'm here to help troubleshoot. Let's gather some information about the error.",
  supportedInputs: [{
    id: "fetch_error_data",
    type: "FUNCTIONAL_MULTI_ATTACHMENT",
    displayName: "Fetch Error Info",
    onInvoke: ({ callback, currentMessageAttachments }) => {
      // either call your API or trigger an in-app modal or other UI
      setTimeout(() => {
        const errorLogAttachment: MessageAttachment = {
          id: "error_log_attachment",
          title: "Error Log",
          content: "Error: Unable to connect to database\nTimestamp: 2023-04-15T14:30:00Z",
          contentType: { type: "CODE", contentInputLabel: "Error Log", language: "plaintext" }
        };
        // pass information back to the workflow
        callback([...currentMessageAttachments, errorLogAttachment]);
      }, 1000);
    },
  } as WorkflowFunctionalMultiInput],
};

WorkflowFunctionalMultiInput

This input type allows you to provide your own custom logic to pass information back to the chatbot as an attachment. This custom logic might be your own form, modal, or even via APIs that fetch information about a user from your own downstream services.

PropertyTypeDescription
idstringRequired. Id of the input.
type"FUNCTIONAL_MULTI_ATTACHMENT"Required.
displayNamestringRequired. Button label in the UI that triggers the onInvoke function.
onInvoke(OnInvokeArgs) => void See below.Required. Function that runs when the button is clicked.

OnInvokeArgs

onInvoke is called with the following arguments:

PropertyTypeDescription
workflowWorkflowThe workflow the user has selected.
selectedInputTypeWorkflowModalSingleInputWorkflowFunctionalMultiInput[]
callback(messageAttachments: MessageAttachment[]) => voidFunction to update the message attachments. This will override what is currently in state so append any new attachments to currentMessageAttachments to avoid removing an attachment. Learn more.
currentMessageAttachmentsMessageAttachment[]The message attachments that user attached. Learn more.

On this page