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 }) => {
    await execute({
      instructions: "You are a helpful assistant.",
    });
  },
});

Channel matching

The channel property determines which integration channels the Conversation handles:

All channels

export default new Conversation({
  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: "chat.channel",
  handler: async ({ execute, message }) => {
    const userMessage = message.payload.text;
    await execute({
      instructions: `You are a helpful assistant. The user said: ${userMessage}`,
    });
  },
});

When using channel: "*", the message type is unknown since the concrete channel is only known at runtime. Use a specific channel to get full type safety on message properties.

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. It exposes conversation.id (the conversation ID) and conversation.channel (the channel name) as read-only properties.

Loading a conversation by ID

You can load any conversation by passing its ID as a string to the static Conversation.get() method:

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

const otherConversation = await Conversation.get("your-conversation-id");
await otherConversation.send({ type: "text", payload: { text: "Hello from another 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";

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

channel · string | string[] | '*' · required

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

handler · (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.

state · z.ZodTypeAny

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

events · string[]

Optional array of event names this conversation should listen to. Supports integration events with a conversationId (e.g., "webchat:conversationStarted") and custom events defined in agent.config.ts. By default, conversations only receive messages, not events.

chat · (props: object) => Chat

Optional function that returns a custom Chat instance for managing message sending and transcript tracking in the conversation.

Handler parameters

The handler receives different parameters depending on the request type. Check the type field to determine what kind of request you’re handling.

All handler types share these common parameters:

Show Common handler parameters

conversation · object · required

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

state · any · required

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

client · object · required

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

execute · (props: object) => Promise<any> · required

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

chat · Chat · required

Chat instance for sending messages and managing the conversation transcript.

channel · string · required

The channel this message or event came from.

Message handler

When type is "message":

Show Message handler parameters

type · 'message' · required

Indicates this is a message request.

message · object · required

Message object containing type and payload properties. Runtime type is channel dependent.

Event handler

When type is "event":

Show Event handler parameters

type · 'event' · required

Indicates this is an event request.

event · object · required

Event object containing type and payload properties from integrations or custom events. Runtime type is channel dependent.

To receive events in a conversation, you must specify the events prop on the Conversation definition. By default, conversations only receive messages.

Workflow request handler

When type is "workflow_request":

Show Workflow request handler parameters

type · 'workflow_request' · required

Indicates this is a workflow data request.

request · object · required

Workflow request object containing workflow and step information.

Show Request properties

type · string · required

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

workflow · object · required

The workflow instance that made the request.

step · string · required

The name of the step that made the request.

Workflow callback handler

When type is "workflow_callback":

Show Workflow callback handler parameters

type · 'workflow_callback' · required

Indicates this is a workflow callback event.

completion · object · required

Workflow callback object containing information about the completed workflow.

Execute props

The execute function accepts the following props:

Show Execute props

instructions · string | (() => string) | (() => Promise<string>) · required

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

tools · object[]

Optional array of tools the agent can use.

objects · object[]

Optional array of objects the agent can interact with.

exits · Record<string, object>

Optional record of exit handlers.

signal · AbortSignal

Optional abort signal to cancel execution.

hooks · object

Optional hooks for customizing behavior (onBeforeTool, onAfterTool, onTrace, onBeforeExecution, onExit, onIterationStart, onIterationEnd).

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

Optional temperature for the AI model. Defaults to 0.7.

model · string | string[] | (() => string | string[]) | (() => Promise<string | string[]>)

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

reasoningEffort · 'low' | 'medium' | 'high' | 'dynamic' | 'none'

Optional reasoning effort for models that support reasoning. "none" disables reasoning, "dynamic" lets the provider decide.

knowledge · object[]

Optional array of knowledge bases to use.

iterations · number

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