In-App Copilots provide intelligent, context-aware assistance directly within your application, enhancing user experience and streamlining interactions. Use context and guidance to provide dynamic user or product specific information or workflows to guide users through complex tasks or common scenarios.

Context and guidance

Context and guidance can be passed in via the aiChatSettings.

context

context can be used to provide additional details about the user that might be helpful information for the bot to consider while answering.

Often, this is used to dynamically provide information about the user that can be inferred by their account (if authenticated to your application) or based on the page they are currently viewing.

Examples

For providing context based on the user:

`The user is currently viewing documentation page ${url}.`
"The user is new to the platform." // (for user life cycle stages)

For providing context based on a product:

`The question is about ${product}.` // (for teams with multiple products)
"The user is using the cloud hosted version of the application." // (for teams with multiple versions or pricing tiers)

Frame context as a single phrase or a bullet point list.

context applies to the entire chat session.

guidance

guidance can be used to customize the behavior of the bot response using natural language. You can think of guidance as custom instructions for the large language model.

We've already optimized chat responses to have proper guardrails for staying on topic, tone, brand-protection, etc.

However, guidance is useful when you want to go beyond the default behavior.

Examples

We recommend using the below format:

<law>
  <name>Sprinkle of Humor</name>
  <conditions>
    <condition>For all questions where the user has a neutral or positive tone</condition>
  </conditions>
  <action>Add a bit of humour to your answer while still answering the user's question</action>
</law>
<law>
  <name>Be brief</name>
  <conditions>
    <condition>For all responses</condition>
  </conditions>
  <action>Limit your answer to two sentences.</action>
</law>
<law>
  <name>Clarify app type</name>
  <conditions>
    <condition>When asking how to add to their application</condition>
    <condition>And it is unclear what SDK or application framework they are using</condition>
  </conditions>
  <action>Briefly enumerate some options that may apply to them and ask a clarifying question</action>
</law>

guidance applies to the entire chat session.

You can configure guidance that will apply to all chats of a project as Custom Rules under Project > Settings in the Inkeep dashboard. If you'd like to customize guidance on a per-integration basis or dynamically, then use this property in the widget settings instead.

Workflows

Workflows allow you to create app-specific flows that are specific to common scenarios your users may face. This often maps to specific tasks in your onboarding or user activation funnel.

Workflows support:

  • 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.
contentTypeWorkflowCodeContentType | WorkflowTextContentTypeRequired. Type of content user is inputting. Learn more.
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
contentTypeWorkflowCodeContentType | WorkflowTextContentTypeRequired. Learn more.
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.
selectedInputTypeWorkflowModalSingleInput | WorkflowFunctionalMultiInput[]The input type the user has selected.
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.