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

Basic Configuration

import { type Workflow } from "@inkeep/cxkit-types";
 
const exampleWorkflow: Workflow = {
  id: "example_workflow",
  displayName: "Help me integrate with my app",
  goals: [
    "Identify the platform that the user is looking to add Inkeep on",
    "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",
      isRequired: true,
    },
  ],
  guidance: [
    "If not clear from the user's message, ask clarifying questions to understand the underlying platform",
    "If the platform is not detailed in our quickstarts, then ask whether it's a React or JavaScript based platform",
  ],
  initialReplyMessage: "Happy to help. Where are you looking to add Inkeep?",
};

Core Configuration Options

Property	Type	Required	Description
`id`	`string`	Yes	Unique identifier for the workflow
`displayName`	`string`	Yes	Label shown to users in the UI
`goals`	`string[]`	Yes	Goals for the workflow (not visible to users)
`informationToCollect`	`WorkflowInformationToCollect[]`	Yes	Information to collect from users
`botPersona`	`string`	No	The persona/character the bot should adopt
`context`	`string[]`	No	Additional context for the LLM (not visible to users)
`guidance`	`string[]`	No	Additional guidance for the LLM (not visible to users)
`initialReplyMessage`	`string`	Yes	First message from the bot when workflow is selected
`supportedInputs`	`WorkflowInputTypes[]`	No	Configuration for input collection methods

Information Collection

The WorkflowInformationToCollect interface defines what information needs to be gathered:

interface WorkflowInformationToCollect {
  description: string; // What information to collect
  required: boolean; // Whether this information is required
}

Input Types

There are two types of inputs supported for collecting information from users:

The WorkflowModalSingleInput type opens a built-in modal with a form:

const modalInput: WorkflowModalSingleInput = {
  id: "error_log_input",
  type: "MODAL",
  displayName: "Share Error Log", // Button label in UI
  contentType: {
    type: "CODE",
    language: "plaintext",
    contentInputLabel: "Error Log",
    attachmentIcon: {
      // Optional icon next to title
      builtIn: "FaCode",
    },
  },
  workflowModalProps: {
    titleInputLabel: "Error Description",
    modalHelpText: "Please paste your error log here",
  },
};

Property	Type	Required	Description
`id`	`string`	Yes	Unique identifier for the input
`type`	`"MODAL"`	Yes	Specifies this is a modal input
`displayName`	`string`	Yes	Button label in the UI
`contentType`	`MessageAttachmentContentType`	Yes	Type of content to collect
`workflowModalProps`	`WorkflowModalProps`	No	Additional modal configuration

Content Types

Two content types are supported:

Code Content:

interface WorkflowCodeContentType {
  type: "CODE";
  language: string;
  contentInputLabel: string;
  attachmentIcon?: InkeepCustomIcon;
}

Text Content:

interface WorkflowTextContentType {
  type: "text";
  contentInputLabel: string;
  attachmentIcon?: InkeepCustomIcon;
}

2. Custom Function Input

The WorkflowFunctionalMultiInput type allows you to implement custom logic for collecting information:

const functionalInput: WorkflowFunctionalMultiInput = {
  id: "fetch_error_data",
  type: "FUNCTIONAL_MULTI_ATTACHMENT",
  displayName: "Fetch Error Info",
  onInvoke: (workflow, inputType, callback, currentAttachments) => {
    // Your custom logic here (e.g. API calls, custom UI)
    const newAttachment: MessageAttachment = {
      id: "error_log",
      title: "System Error Log",
      content: "Error details...",
      contentType: {
        type: "CODE",
        language: "plaintext",
        contentInputLabel: "Error Log",
      },
    };
 
    callback([...currentAttachments, newAttachment]);
  },
};

Functional Input Configuration

Property	Type	Required	Description
`id`	`string`	Yes	Unique identifier for the input
`type`	`"FUNCTIONAL_MULTI_ATTACHMENT"`	Yes	Specifies this is a functional input
`displayName`	`string`	Yes	Button label in the UI
`onInvoke`	`Function`	Yes	Callback function when input is triggered

The onInvoke function receives:

workflow: Current workflow configuration
selectedInputType: The input type that was selected
callback: Function to pass back collected information
currentMessageAttachments: Current attachments in the chat

The MessageAttachment interface defines the structure of attachments that can be added to messages:

interface MessageAttachment {
  contentType: MessageAttachmentContentType;
  title: string;
  content: string;
  id: string;
  context?: string[];
}

Complete Example

Here's a complete workflow example for a technical support scenario:

import { type Workflow } from "@inkeep/cxkit-types";
 
const supportWorkflow: Workflow = {
  id: "technical_support",
  displayName: "Technical Support",
  goals: [
    "Identify the technical issue",
    "Collect system information",
    "Provide troubleshooting steps",
  ],
  informationToCollect: [
    {
      description: "Issue description",
      isRequired: true,
    },
    {
      description: "System version",
      isRequired: true,
    },
  ],
  botPersona: "Helpful technical support specialist",
  guidance: [
    "Ask clarifying questions",
    "Request specific error messages",
    "Provide step-by-step solutions",
  ],
  initialReplyMessage:
    "Hello! I'm your technical support assistant. How can I help you today?",
  supportedInputs: [
    {
      id: "error_log",
      type: "MODAL",
      displayName: "Share Error Log",
      contentType: {
        type: "CODE",
        language: "plaintext",
        contentInputLabel: "Error Log",
        attachmentIcon: {
          builtIn: "FaExclamationTriangle",
        },
      },
      workflowModalProps: {
        titleInputLabel: "Error Description",
        modalHelpText:
          "Please paste your error log and provide a brief description",
      },
    },
    {
      id: "system_info",
      type: "FUNCTIONAL_MULTI_ATTACHMENT",
      displayName: "Share System Info",
      onInvoke: (workflow, inputType, callback, currentAttachments) => {
        // Example: Fetch system information
        const systemInfo: MessageAttachment = {
          id: "sys_info",
          title: "System Information",
          content: JSON.stringify(
            {
              os: "macOS 12.0",
              browser: "Chrome 96",
              // ... other system details
            },
            null,
            2
          ),
          contentType: {
            type: "CODE",
            language: "json",
            contentInputLabel: "System Information",
          },
        };
        callback([...currentAttachments, systemInfo]);
      },
    },
  ],
};