> ## Documentation Index
> Fetch the complete documentation index at: https://botpress-ak-docs-20-document-updating-variables-from-outsid.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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/`:

```typescript theme={null}
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:

<CodeGroup>
  ```ts All channels highlight={2} theme={null}
  export default new Conversation({
    channel: "*",
    handler: async ({ execute }) => {
      await execute({
        instructions: "You are a helpful assistant.",
      });
    },
  });
  ```

  ```ts Specific channel highlight={2} theme={null}
  export default new Conversation({
    channel: "webchat.channel",
    handler: async ({ execute }) => {
      await execute({
        instructions: "You are a helpful assistant.",
      });
    },
  });
  ```

  ```ts Array of channels highlight={2-5} theme={null}
  export default new Conversation({
    channel: [
      "chat.channel",
      "webchat.channel"
    ],
    handler: async ({ execute }) => {
      await execute({
        instructions: "You are a helpful assistant.",
      });
    },
  });
  ```
</CodeGroup>

## Conversation handler

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

```typescript highlight={3-8} theme={null}
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:

```typescript highlight={1, 8} theme={null}
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:

```typescript highlight={6-13} theme={null}
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:

```typescript theme={null}
await conversation.send({
  type: "text",
  payload: { text: "Hello!" },
});
```

### Typing indicators

Control typing indicators:

```typescript theme={null}
await conversation.startTyping();
// ... do some work ...
await conversation.stopTyping();
```

### Conversation tags

Access and modify conversation tags:

```typescript theme={null}
// Read tags
const priority = conversation.tags.priority;

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

### Trigger subscriptions

Subscribe a conversation to triggers:

```typescript theme={null}
// 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

<Expandable title="Conversation props">
  <ResponseField name="channel" type="string | string[] | '*'" required>
    Channel specification. Can be a single channel name, an array of channel names, or '\*' to match all channels.
  </ResponseField>

  <ResponseField name="handler" type="(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.
  </ResponseField>

  <ResponseField name="state" type="z.ZodTypeAny">
    Optional Zod schema defining the conversation state structure. Defaults to an empty object if not provided.
  </ResponseField>

  <ResponseField name="startFromTrigger" type="(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.
  </ResponseField>
</Expandable>

### 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"`:

<Expandable title="Message handler parameters">
  <ResponseField name="type" type="'message'" required>
    Indicates this is a message request.
  </ResponseField>

  <ResponseField name="message" type="any" required>
    Message object containing the user's message data. Typed by `ConversationInstance` at runtime based on the channel.
  </ResponseField>

  <ResponseField name="conversation" type="object" required>
    Conversation instance providing methods to interact with the conversation (send messages, manage state, etc.).
  </ResponseField>

  <ResponseField name="state" type="any" required>
    Mutable conversation state object. Changes to this object are automatically persisted. Typed based on your state schema.
  </ResponseField>

  <ResponseField name="client" type="object" required>
    Botpress client for making API calls (tables, events, etc.).
  </ResponseField>

  <ResponseField name="execute" type="(props: object) => Promise<any>" required>
    Function to execute autonomous AI logic. Used to run the agent with instructions, tools, knowledge bases, etc.

    <Expandable title="Execute props">
      <ResponseField name="instructions" type="string | (() => string) | (() => Promise<string>)" required>
        Instructions for the AI agent. Can be a string or a function that returns a string.
      </ResponseField>

      <ResponseField name="tools" type="object[]">
        Optional array of tools the agent can use.
      </ResponseField>

      <ResponseField name="objects" type="object[]">
        Optional array of objects the agent can interact with.
      </ResponseField>

      <ResponseField name="exits" type="Record<string, object>">
        Optional record of exit handlers.
      </ResponseField>

      <ResponseField name="signal" type="AbortSignal">
        Optional abort signal to cancel execution.
      </ResponseField>

      <ResponseField name="hooks" type="object">
        Optional hooks for customizing behavior (`onBeforeTool`, `onAfterTool`, `onTrace`, etc.).
      </ResponseField>

      <ResponseField name="temperature" type="number | (() => number) | (() => Promise<number>)">
        Optional temperature for the AI model. Defaults to 0.7.
      </ResponseField>

      <ResponseField name="model" type="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.
      </ResponseField>

      <ResponseField name="knowledge" type="object[]">
        Optional array of knowledge bases to use.
      </ResponseField>

      <ResponseField name="iterations" type="number">
        Optional maximum number of iterations (loops). Defaults to 10.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Expandable>

#### Event handler

When `type` is `"event"`:

<Expandable title="Event handler parameters">
  <ResponseField name="type" type="'event'" required>
    Indicates this is an event request.
  </ResponseField>

  <ResponseField name="event" type="any" required>
    Event object containing event data from integrations or system events. Typed by `ConversationInstance` at runtime based on the channel.
  </ResponseField>

  <ResponseField name="conversation" type="object" required>
    Conversation instance providing methods to interact with the conversation (send messages, manage state, etc.).
  </ResponseField>

  <ResponseField name="state" type="any" required>
    Mutable conversation state object. Changes to this object are automatically persisted. Typed based on your state schema.
  </ResponseField>

  <ResponseField name="client" type="object" required>
    Botpress client for making API calls (tables, events, etc.).
  </ResponseField>

  <ResponseField name="execute" type="(props: object) => Promise<any>" required>
    Function to execute autonomous AI logic. Used to run the agent with instructions, tools, knowledge bases, etc.

    <Expandable title="Execute props">
      <ResponseField name="instructions" type="string | (() => string) | (() => Promise<string>)" required>
        Instructions for the AI agent. Can be a string or a function that returns a string.
      </ResponseField>

      <ResponseField name="tools" type="object[]">
        Optional array of tools the agent can use.
      </ResponseField>

      <ResponseField name="objects" type="object[]">
        Optional array of objects the agent can interact with.
      </ResponseField>

      <ResponseField name="exits" type="Record<string, object>">
        Optional record of exit handlers.
      </ResponseField>

      <ResponseField name="signal" type="AbortSignal">
        Optional abort signal to cancel execution.
      </ResponseField>

      <ResponseField name="hooks" type="object">
        Optional hooks for customizing behavior (`onBeforeTool`, `onAfterTool`, `onTrace`, etc.).
      </ResponseField>

      <ResponseField name="temperature" type="number | (() => number) | (() => Promise<number>)">
        Optional temperature for the AI model. Defaults to 0.7.
      </ResponseField>

      <ResponseField name="model" type="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.
      </ResponseField>

      <ResponseField name="knowledge" type="object[]">
        Optional array of knowledge bases to use.
      </ResponseField>

      <ResponseField name="iterations" type="number">
        Optional maximum number of iterations (loops). Defaults to 10.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Expandable>

#### Workflow request handler

When `type` is `"workflow_request"`:

<Expandable title="Workflow request handler parameters">
  <ResponseField name="type" type="'workflow_request'" required>
    Indicates this is a workflow data request.
  </ResponseField>

  <ResponseField name="request" type="object" required>
    Workflow request object containing workflow and step information.

    <Expandable title="Request properties">
      <ResponseField name="type" type="string" required>
        The request type in the format `"workflowName:requestName"`.
      </ResponseField>

      <ResponseField name="workflow" type="object" required>
        The workflow instance that made the request.
      </ResponseField>

      <ResponseField name="step" type="string" required>
        The name of the step that made the request.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="conversation" type="object" required>
    Conversation instance providing methods to interact with the conversation (send messages, manage state, etc.).
  </ResponseField>

  <ResponseField name="state" type="any" required>
    Mutable conversation state object. Changes to this object are automatically persisted. Typed based on your state schema.
  </ResponseField>

  <ResponseField name="client" type="object" required>
    Botpress client for making API calls (tables, events, etc.).
  </ResponseField>

  <ResponseField name="execute" type="(props: object) => Promise<any>" required>
    Function to execute autonomous AI logic. Used to run the agent with instructions, tools, knowledge bases, etc.

    <Expandable title="Execute props">
      <ResponseField name="instructions" type="string | (() => string) | (() => Promise<string>)" required>
        Instructions for the AI agent. Can be a string or a function that returns a string.
      </ResponseField>

      <ResponseField name="tools" type="object[]">
        Optional array of tools the agent can use.
      </ResponseField>

      <ResponseField name="objects" type="object[]">
        Optional array of objects the agent can interact with.
      </ResponseField>

      <ResponseField name="exits" type="Record<string, object>">
        Optional record of exit handlers.
      </ResponseField>

      <ResponseField name="signal" type="AbortSignal">
        Optional abort signal to cancel execution.
      </ResponseField>

      <ResponseField name="hooks" type="object">
        Optional hooks for customizing behavior (`onBeforeTool`, `onAfterTool`, `onTrace`, etc.).
      </ResponseField>

      <ResponseField name="temperature" type="number | (() => number) | (() => Promise<number>)">
        Optional temperature for the AI model. Defaults to 0.7.
      </ResponseField>

      <ResponseField name="model" type="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.
      </ResponseField>

      <ResponseField name="knowledge" type="object[]">
        Optional array of knowledge bases to use.
      </ResponseField>

      <ResponseField name="iterations" type="number">
        Optional maximum number of iterations (loops). Defaults to 10.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Expandable>

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