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:

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.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

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.

startFromTrigger · (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

type · 'message' · required

Indicates this is a message request.

message · any · required

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

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.

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, etc.).

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.

knowledge · object[]

Optional array of knowledge bases to use.

iterations · number

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

Event handler

When type is "event":

Show Event handler parameters

type · 'event' · required

Indicates this is an event request.

event · any · required

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

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.

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, etc.).

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.

knowledge · object[]

Optional array of knowledge bases to use.

iterations · number

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

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.

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.

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, etc.).

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.

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.