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: "*",
  handler: async ({ execute, message }) => {
    const userMessage = message.payload.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. 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 its ID using the static Conversation.get() method:

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

const otherConversation = await Conversation.get("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 factory function to provide a custom Chat instance for the conversation.

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.

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. Typed based on the channel at runtime.

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. Typed based on the channel at runtime.

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.

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.

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