Conversations

Conversations are the primary way your agent handles user messages. Each conversation handler defines how your agent responds to messages from specific channels.

Creating a conversation

Create a conversation handler in src/conversations/:

import { Conversation } from "@botpress/runtime";

export default new Conversation({
  channel: "*",
  handler: async ({ execute, message }) => {
    await execute({
      instructions: "You are a helpful assistant.",
    });
  },
});

Channel matching

The channel property determines which integration channels the Conversation handles:

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful assistant.",
    });
  },
});

export default new Conversation({
  channel: "webchat.channel",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful assistant.",
    });
  },
});

export default new Conversation({
  channel: [
    "chat.channel",
    "webchat.channel"
  ],
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful assistant.",
    });
  },
});

Conversation handler

The handler function receives context about the incoming message and provides APIs to execute your agent’s logic:

export default new Conversation({
  channel: "*",
  handler: async ({ execute, message }) => {
    const userMessage = message.text;
    await execute({
      instructions: `You are a helpful assistant. The user said: ${userMessage}`,
    });
  },
});

Using knowledge bases

Provide knowledge to your agent’s AI model:

import { WebsiteKB } from "../knowledge/docs";

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful assistant.",
      knowledge: [WebsiteKB],
    });
  },
});

Using hooks

Add hooks to customize behavior at different stages:

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful assistant.",
      hooks: {
        onBeforeTool: async (props) => {
          // Custom logic before tool execution
        },
        onTrace: (props) => {
          // Log or monitor trace events
        },
      },
    });
  },
});

Conversation instance

The handler receives a conversation object that provides methods to interact with the current conversation:

Sending messages

Send a message to the conversation:

await conversation.send({
  type: "text",
  payload: { text: "Hello!" },
});

Typing indicators

Control typing indicators:

await conversation.startTyping();
// ... do some work ...
await conversation.stopTyping();

Conversation tags

Access and modify conversation tags:

// Read tags
const priority = conversation.tags.priority;

// Set tags
conversation.tags.priority = "high";

Trigger subscriptions

Subscribe a conversation to triggers:

// Subscribe to a trigger
await conversation.subscribeToTrigger("myTrigger");

// Subscribe with a key for filtered triggers
await conversation.subscribeToTrigger("myTrigger", "specific-key");

// Unsubscribe
await conversation.unsubscribeFromTrigger("myTrigger");

Multiple conversations

You can create multiple conversation handlers for different channels or use cases:

src/conversations/
├── webchat.ts        # Webchat-specific handler
├── slack.ts          # Slack-specific handler
└── support.ts        # Support-focused handler

Reference

Conversation props

Show Conversation props

string | string[] | '*'

required

Channel specification. Can be a single channel name, an array of channel names, or ’*’ to match all channels.

(props: object) => Promise<void> | void

required

Handler function that processes incoming messages and events. The props object structure is documented in the handler parameters section below.

z.ZodTypeAny

Optional Zod schema defining the conversation state structure. Defaults to an empty object if not provided.

(event: any) => Promise<string | false> | string | false

Optional function to determine if a conversation should start from a trigger event. Returns a conversation ID or false.

Handler parameters

The handler function receives different parameters depending on the incoming request type. The handler uses a discriminated union based on the type field:

Message handler

When type is "message":

Show Message handler parameters

'message'

required

Indicates this is a message request.

any

required

Message object containing the user’s message data. Typed by ConversationInstance at runtime based on the channel.

object

required

Conversation instance providing methods to interact with the conversation (send messages, manage state, etc.).

any

required

Mutable conversation state object. Changes to this object are automatically persisted. Typed based on your state schema.

object

required

Botpress client for making API calls (tables, events, etc.).

(props: object) => Promise<any>

required

Function to execute autonomous AI logic. Used to run the agent with instructions, tools, knowledge bases, etc.

Show Execute props

string | (() => string) | (() => Promise<string>)

required

Instructions for the AI agent. Can be a string or a function that returns a string.

object[]

Optional array of tools the agent can use.

object[]

Optional array of objects the agent can interact with.

Record<string, object>

Optional record of exit handlers.

AbortSignal

Optional abort signal to cancel execution.

object

Optional hooks for customizing behavior (onBeforeTool, onAfterTool, onTrace, etc.).

number | (() => number) | (() => Promise<number>)

Optional temperature for the AI model. Defaults to 0.7.

Optional model name(s) to use. Can be a string, array of strings, or a function that returns either.

object[]

Optional array of knowledge bases to use.

number

Optional maximum number of iterations (loops). Defaults to 10.

Event handler

When type is "event":

Show Event handler parameters

'event'

required

Indicates this is an event request.

any

required

Event object containing event data from integrations or system events. Typed by ConversationInstance at runtime based on the channel.

object

required

Conversation instance providing methods to interact with the conversation (send messages, manage state, etc.).

any

required

Mutable conversation state object. Changes to this object are automatically persisted. Typed based on your state schema.

object

required

Botpress client for making API calls (tables, events, etc.).

(props: object) => Promise<any>

required

Function to execute autonomous AI logic. Used to run the agent with instructions, tools, knowledge bases, etc.

Show Execute props

string | (() => string) | (() => Promise<string>)

required

Instructions for the AI agent. Can be a string or a function that returns a string.

object[]

Optional array of tools the agent can use.

object[]

Optional array of objects the agent can interact with.

Record<string, object>

Optional record of exit handlers.

AbortSignal

Optional abort signal to cancel execution.

object

Optional hooks for customizing behavior (onBeforeTool, onAfterTool, onTrace, etc.).

number | (() => number) | (() => Promise<number>)

Optional temperature for the AI model. Defaults to 0.7.

Optional model name(s) to use. Can be a string, array of strings, or a function that returns either.

object[]

Optional array of knowledge bases to use.

number

Optional maximum number of iterations (loops). Defaults to 10.

Workflow request handler

When type is "workflow_request":

Show Workflow request handler parameters

'workflow_request'

required

Indicates this is a workflow data request.

object

required

Workflow request object containing workflow and step information.

Show Request properties

string

required

The request type in the format "workflowName:requestName".

object

required

The workflow instance that made the request.

string

required

The name of the step that made the request.

object

required

Conversation instance providing methods to interact with the conversation (send messages, manage state, etc.).

any

required

Mutable conversation state object. Changes to this object are automatically persisted. Typed based on your state schema.

object

required

Botpress client for making API calls (tables, events, etc.).

(props: object) => Promise<any>

required

Function to execute autonomous AI logic. Used to run the agent with instructions, tools, knowledge bases, etc.

Show Execute props

string | (() => string) | (() => Promise<string>)

required

Instructions for the AI agent. Can be a string or a function that returns a string.

object[]

Optional array of tools the agent can use.

object[]

Optional array of objects the agent can interact with.

Record<string, object>

Optional record of exit handlers.

AbortSignal

Optional abort signal to cancel execution.

object

Optional hooks for customizing behavior (onBeforeTool, onAfterTool, onTrace, etc.).

number | (() => number) | (() => Promise<number>)

Optional temperature for the AI model. Defaults to 0.7.

Optional model name(s) to use. Can be a string, array of strings, or a function that returns either.

object[]

Optional array of knowledge bases to use.

number

Optional maximum number of iterations (loops). Defaults to 10.

Each conversation file should export a default Conversation instance. The ADK automatically discovers and registers all conversations in the src/conversations/ directory.

Get started

ADK

Studio

Integrations

Webchat

Desk

Creating a conversation

Channel matching

Conversation handler

Using knowledge bases

Using hooks

Conversation instance

Sending messages

Typing indicators

Conversation tags

Trigger subscriptions

Multiple conversations

Reference

Conversation props

Handler parameters

Message handler

Event handler

Workflow request handler

​Creating a conversation

​Channel matching

​Conversation handler

​Using knowledge bases

​Using hooks

​Conversation instance

​Sending messages

​Typing indicators

​Conversation tags

​Trigger subscriptions

​Multiple conversations

​Reference

​Conversation props

​Handler parameters

​Message handler

​Event handler

​Workflow request handler

Creating a conversation

Channel matching

Conversation handler

Using knowledge bases

Using hooks

Conversation instance

Sending messages

Typing indicators

Conversation tags

Trigger subscriptions

Multiple conversations

Reference

Conversation props

Handler parameters

Message handler

Event handler

Workflow request handler